Documentation#

Guidance on how QRMI documentation is structured, maintained, and generated for publication.

Overview#

Sphinx#

These pages are built using Sphinx, a documentation generator. The process of building these HTML pages from the reStructured Text source files is automated via the Sphinx Documentation GitHub Action.

The GitHub Action is responsible for two tasks; building the documentation, then deploying it to GitHub Pages.

  • Pushing to a feature branch with an associated PR triggers the build job, which carries out checks ensuring the documentation builds correctly.

  • Pushing to main triggers both the build and deploy jobs, which build the documentation and deploy it to GitHub Pages.

Further information about Sphinx can be found in the Sphinx documentation.

pandoc#

Sphinx does not support Markdown natively, so any Markdown files must be converted to reStructured Text before they can be included in the documentation.

pandoc is an open-source tool that can assist with this conversion. Once installed, you can convert a .md file to an .rst file, you could do so by running the following command:

pandoc -f markdown -t rst -o output.rst input.md

Multiple Markdown files can be converted in bulk:

for f in *.md; do
 pandoc -s "$f" -o "${f%.md}.rst"
done

More advanced information on pandoc usage can be found in the pandoc documentation.

Adding Documentation#

All documentation files are stored in the docs directory. The index.rst file defines the content of the landing page, as well as structure of the documentation (as seen in the sidebar).

Sphinx stores built HTML files in the _build directory. Static files, such as images, .css and .js files, are stored in _static and its associated subdirectories.

If you would like to add to the existing documentation, follow these steps:

  1. Create a new reStructured Text (.rst) file in the docs directory. If the file relates to an existing topic, you can place it in the appropriate subdirectory.

  2. In docs/index.rst, add a reference to the new file in the appropriate section of the toctree directive. For example, for a new file called new_topic.rst:

    new_topic.rst#
    .. toctree::
   :maxdepth: 2
   :caption: New Section

   new_topic

  3. Build the documentation locally. If the build is successful, commit and push your changes to the repository.

Local Documentation#

Building Local Documentation#

To build, test and verify the changes locally (and identify any errors):

  1. Install the required dependencies for building the documentation:

    python -m pip install --upgrade pip
pip install -e ".[all, docs]"

  2. Build the documentation and serve it locally:

    cd docs/
sphinx-autobuild . _build/html/

The build process will identify any errors, such as missing references, toctree issues or syntax errors.

API References#

QRMI’s hosted API references can be accessed using the below site links:

To build the API references locally, follow the instructions below.

Prerequisites#

  • Doxygen (for generating C API document)

    • dnf install doxygen for Linux(RHEL/CentOS/Rocky Linux etc)

    • apt install doxygen for Linux(Ubuntu etc.)

    • brew install doxygen for MacOS

Building Local API References#

  1. Build the Rust API docs using the following command:

. ~/.cargo/env
cargo doc --no-deps --open

Hosting the Sphinx API References Locally#

These API references are automatically built as part of QRMI’s CI/CD pipeline and aren’t automatically available when the repository is cloned. Building the API references locally and moving them into the appropriate subdirectories will allow you to access them via your local build of the documentation.

  1. Build the Rust API docs using the following command:

. ~/.cargo/env
cargo doc --no-deps

  1. Copy the generated documentation into the appropriate subdirectory:

mkdir -p docs/_build/html/rust
cp -R target/doc/* docs/_build/html/rust/

  1. Build the documentation and serve it locally:

cd docs/
sphinx-autobuild . _build/html/

Theming and Customisation#

Theming and customisation (such as extensions, HTML options, etc.) are configured in docs/conf.py.

This documentation uses the Shibuya theme.