Skip to main content

How to contribute to doxygen2docusaurus

GitHub package.json version NPM Version licence GitHub issues GitHub pulls TypeScript ESLint

This page is for the contributors who add new features or fix bugs in the Doxygen Documentation Converter project, and describes how to build and test the package.

Prerequisites​

@xpack/doxygen2docusaurus is a portable Node.js project; development can be conducted on macOS, GNU/Linux, and Windows (although some npm scripts must be executed within a Git Bash terminal).

The prerequisites are:

  • git
  • node >= 20.0
  • npm

To check the compatibility with the oldest supported node version, switch to it:

nvm use --lts 20
code

Obtain project sources​

The project is hosted on GitHub:

Branches

This project uses multiple branches:

  • master, containing the latest stable version (default)
  • development, containing the current development version
  • website, containing the current website content; pushes to this branch automatically trigger publication of the main website
  • webpreview, containing the current preview website content; pushes to this branch automatically trigger publication of the preview website

All development is conducted in the development branch, and contributions via Pull Requests should be directed to this branch.

When new releases are published, the master branch is rebased onto development.

To clone the stable branch (master), execute the following commands in a terminal (on Windows use the Git Bash console):

rm -rf ~/Work/xpack/doxygen2docusaurus-cli-ts.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch master \
  https://github.com/xpack/doxygen2docusaurus-cli-ts.git \
  ~/Work/xpack/doxygen2docusaurus-cli-ts.git
For development purposes, clone the development branch.
rm -rf ~/Work/xpack/doxygen2docusaurus-cli-ts.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch development \
  https://github.com/xpack/doxygen2docusaurus-cli-ts.git \
  ~/Work/xpack/doxygen2docusaurus-cli-ts.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpack/doxygen2docusaurus-cli-ts.git pull
tip

To contribute Pull Requests, fork the project and ensure that Copy the master branch only is disabled.

Use the development branch, and direct the Pull Requests to the same branch.

During development, it is convenient to maintain a writable instance of the source code to enable changes in parallel with the parent project.

To facilitate the use of a writable instance of this source code in other projects, add a link from the user's global npm store to this local development folder:

npm --prefix ~/Work/xpack/doxygen2docusaurus-cli-ts.git link

And in the projects that refer to it:

npm link @xpack/doxygen2docusaurus

Satisfy dependencies​

npm install

Start the compile background task​

The TypeScript compiler can automatically recompile modified files. For this, start it in watch mode.

npm run compile-watch

Language standard compliance​

The current version is compiled with TypeScript 5.9.3:

The compiler is configured to produce ECMAScript6 es2020 files that can be imported by any other project either via import.

For more details on how to configure tsconfig.json, please see:

Style​

As style, the project uses typescript-eslint, a set of rules for static analysis of JavaScript and TypeScript code

For spacial cases, it is possible to configure/disable some rules.

/* eslint-disable-next-line no-xxx-yyy */

The known rules are documented in the eslint project.

Known and accepted exceptions:

  • none

Documentation metadata​

The documentation metadata uses the TSDoc tags, without explicit types, as they are provided by TypeScript.

Tips and tricks​

To trace which files module imports resolve to, enable TypeScript module resolution tracing:

    "compile": "tsc --traceResolution  -p ./",
Last updated on