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

The commands included in online user documentation are specified in all_qunex_commands list in python/gmri file.

New commands should be added to the list as tuples formatted as:

(full_name, description, language),

where:

• full_name is the function's name including Python-like module path,
• description is a short description,
• language is one of "bash", "matlab", "python", or "r".

Python example:

("qx_utilities.processing.fsl.dwi_f99", "Runs FSL F99 command.", "python"),

MATLAB example:

("qx_mri.general.general_plot_bold_timeseries", "Creates and saves a plot of BOLD timeseries.", "matlab"),

Bash example:

("qx_utilities.bash.dwi_bedpostx_gpu", "Runs FSL GPU-enabled bedpostx.", "bash"),

R example:

("qx_utilities.r.bold_movement", "Plots movement data, creates movement reports and information for data scrubbing.", "r"),

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

Also note that additional configuration is required to add Python functions from folders other than $QUNEXPATH/python/qx_utilities. See code inside $QUNEXPATH/docs for an example how the qx_mice Python module was added.

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 commands listed in [Adding and removing commands](#Adding and removing commands) section above and are generated in the docs/api/gmri directory. They are formatted in reStructuredText and used by 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.