How to install doxygen2docusaurus

Prerequisites

Installing doxygen2docusaurus requires:

• A recent version of Node.js (specified as "engines.node": ">=20.0")
• A recent version of npm which is installed alongside Node.js

For those new to Node.js, it is highly recommended to read the instructions on the xPack Prerequisites page.

Quick instructions

For those who have already completed the installation steps on the xPack Prerequisites page and are familiar with the process, here are the necessary commands. Simply copy and paste them into your terminal. When you hover the mouse over the command, a copy button will appear on the right side; click it to copy the command.

Windows

Download the Windows Prebuilt Installer (a node-v*-x64.msi file) from the Download Node.js page. Select the latest LTS version and install it as usual, ensuring you have administrative rights.

tip

Unless specifically required, refrain from selecting the Tools for Native Modules during installation, as this will result in the installation of some very large Microsoft tools.

Although not mandatory, it is recommended to update npm to the latest version:

npm install -location=global npm@latest

Update the user Path and make it persistent:

set Path=%APPDATA%\npm;%Path%
setx Path "%APPDATA%\npm;%Path%"

Configure PowerShell to allow the execution of node.js applications:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser

macOS

To install node via the nvm version manager, execute the following script in your shell:

curl https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh | ${SHELL}

export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"

tip

This script not only installs node and npm but also xpm.

GNU/Linux

To install node via the nvm version manager, execute the following script in your shell:

wget -q -O - https://raw.githubusercontent.com/xpack/assets/master/scripts/install-nvm-node-npm-xpm.sh | ${SHELL}

export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"

tip

This script not only installs node and npm but also xpm.

Installation

The package is available as @xpack/doxygen2docusaurus from the public npmjs repository; it may be added as a development dependency to any npm project or it may be installed into the user's global environment.

Project installation

The command to install the latest available version of @xpack/doxygen2docusaurus as a development dependency in an npm project is:

npm install @xpack/doxygen2docusaurus@latest --save-dev

For a specific version, use the explicit version numbers:

npm install @xpack/doxygen2docusaurus@2.1.0 --save-dev

Global installation

Since the package includes command-line tools, it may also be installed globally and utilised in any project.

npm install --location=global @xpack/doxygen2docusaurus@latest

For a specific version, use the explicit version numbers:

npm install --location=global @xpack/doxygen2docusaurus@2.1.0

Windows

On Windows, global Node.js packages are installed in the user home folder, within %APPDATA%\npm (such as C:\Users\ilg\AppData\Roaming\npm), and managing packages does not require administrative rights.

The result of installing @xpack/doxygen2docusaurus is a set of files in the %APPDATA%\npm folder:

C:\>dir "%APPDATA%"\npm\doxygen2docusaurus*
 Volume in drive C has no label.
 Volume Serial Number is B02D-925C

 Directory of C:\Users\ilg\AppData\Roaming\npm

29/07/2024  07:24               397 doxygen2docusaurus
29/07/2024  07:24               329 doxygen2docusaurus.cmd
29/07/2024  07:24               821 doxygen2docusaurus.ps1
               3 File(s)          1,547 bytes
               0 Dir(s)  39,088,439,296 bytes free

If you followed the instructions in the prerequisites section, you should already have this path configured and the programme should start normally:

C:>doxygen2docusaurus --version
2.1.0

macOS

On macOS, if you executed the install-nvm-node-npm-xpm.sh scripts described in the previous section, you should already have npm correctly configured to utilise a location in the home folder.

% which doxygen2docusaurus
/Users/ilg/.nvm/versions/node/undefined/bin/doxygen2docusaurus

To test if doxygen2docusaurus starts:

% doxygen2docusaurus --version
2.1.0

Show macOS hidden files

The default location used to install the global packages is below ~/Library, a folder that, due to an unfortunate Apple decision, is hidden for regular browsing in Finder.

To make it visible again, utilise:

/usr/bin/chflags nohidden ~/Library
xattr -d com.apple.FinderInfo ~/Library

A more general solution is to make all hidden files visible:

defaults write com.apple.Finder AppleShowAllFiles true
killall Finder

Another frustrating behaviour of the file browser is to hide names beginning with . (dot), which is unfortunate since the binary packages are extracted into a folder named .content.

Fortunately, there is a workaround for this too:

cmd+shift+'.'

This keyboard shortcut functions as a toggle; using it once makes files beginning with dot visible, and using it again reverts to hiding them.

GNU/Linux

On GNU/Linux, by default, when using system packages, global Node.js packages are installed in /usr/local, and managing them requires administrative rights, but if you executed the install-nvm-node-npm-xpm.sh scripts described in the previous section, you should already have npm correctly configured to utilise a location in the home folder.

To test if doxygen2docusaurus starts:

$ which doxygen2docusaurus
/home/ilg/.nvm/versions/node/undefined/bin/doxygen2docusaurus
$ doxygen2docusaurus --version
2.1.0

Uninstall

The command to remove @xpack/doxygen2docusaurus from a project is:

npm uninstall @xpack/doxygen2docusaurus

The command to remove @xpack/doxygen2docusaurus from the global user environment is:

npm uninstall --location=global @xpack/doxygen2docusaurus

npx

If, for any reason, you decide not to install @xpack/doxygen2docusaurus, you can still benefit from it by utilising the npx command, as a trampoline to start doxygen2docusaurus:

$ npx --package @xpack/doxygen2docusaurus -- doxygen2docusaurus --version
2.1.0

However, for regular use, this method may be less convenient, as invoking npx requires a more verbose command.

npm folders

For more details on the folders used by npm, refer to npm-folders.