QuNex documentation is built using Sphinx document generator on Read the Docs servers where it is also being hosted.

Documentation is built on each push to the qunex repository and when a new tag is added. It is built for the develop branch, the master branch (as latest) and for tags. The desired version of documentation can be selected from the left side menu as shown below:

Adding and removing commands

Commands are discovered from the command registry (qx_commands.yaml), which is generated from the .. qx_command: docstrings in the source and built by the build_qx_registry command. Adding, removing or renaming a command is done by editing its docstring and rebuilding the registry — see the Command registry page for the docstring format and build steps.

The documentation build reads the same registry: the pre-build helper registry_docs.py iterates the commands in qx_commands.yaml and, for each, generates the AutoDoc stub used by Sphinx (see [Pre build](#Pre build) below). A command that is in the registry is therefore automatically included in the documentation.

Note that for Bash and R languages only files from $QUNEXPATH/bash/qx_utilities and $QUNEXPATH/r/qx_utilities are supported at this time.

Read the Docs generation process

Read the Docs offers two ways to configure the documentation generation process: use of the admin panel and use of a configuration file (.readthedocs.yaml) that is placed in the root of a project. Both offer some settings that are inaccessible by the other.

Pre build

Before Sphinx build process is run on the Read the Docs server, five additional steps are taken:

1. Latest version of QuNex Wiki is cloned from https://github.com/ULJ-Yale/qunex.wiki.git into docs/wiki directory.
2. Tables of contents [TOC] are removed from all Markdown files since Sphinx does not make use of them.
3. Left side menu and home page are generated as index.rst and HomeMenu.rst from contents in Home.md file. Some values in this step are hardcoded, be aware when modifying Home.md.
4. Docstrings in Bash and R languages are extracted from files in $QUNEXPATH/bash/qx_utilites and $QUNEXPATH/r/qx_utilities directories. Extracted docstrings are saved as $QUNEXPATH/python/qx_utilities/bash.py and $QUNEXPATH/python/qx_utilities/r.py. Note that only files in respective qx_utilities directories are supported for these two languages.
5. Files for every command in the registry (qx_commands.yaml, see [Adding and removing commands](#Adding and removing commands) above) are generated in the docs/api/gmri directory. They are formatted in reStructuredText and used by the AutoDoc extension of Sphinx.

Build

Building documentation locally

In order to build the documentation locally, a set of Sphinx extensions has to be installed on the system. They can be installed with the following command:

python3 -m pip install numpy pydicom myst-parser sphinxcontrib-napoleon sphinxcontrib-matlabdomain sphinx-book-theme sphinx-copybutton sphinxext-opengraph

Use of Python 3.8 is recommended.

Make sure to run $QUNEXPATH/docs/_extras/bash/pre_build.sh to supply wiki pages and generate files as discussed in [Pre build](#Pre build) section.

To build the documentation the command below should be used (make sure you are in the $QUNEXPATH/docs directory):

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

Output files can be found in $QUNEXPATH/docs/_build/html.