Documentation generation guide

This page describes how to generate the Lime Suite NG documentation (the very thing you’re reading right now) on Linux.

Prerequisites

Components needed to generate the Lime Suite NG documentation:

Setup

To set up the environment for the documentation generation, you will need to set up a Python virtual environment (venv).

To set up the environment, run these commands:

python3.8 -m venv venv # Create the virtual environment directory
source venv/bin/activate # Activate the virtual environment
pip install -r requirements.txt # Install all the required dependencies for the generation

Note

One should run these commands in the docs directory.

Generation

In the docs directory, located in the root directory of the repository, while in the venv, run these commands:

cmake -S .. -B ../build # Generate the make file for the suite.
make --no-print-directory -C ../build doc # Build Doxygen documentation
breathe-apidoc --generate class --members --force --output-dir apidoc ../build/xml/ # Generate the class API pages
python add_undoc_members.py # Add a flag to add all undocumented members into the page
make html # Generate the documentation itself

Important

These commands or the script must be run in the venv, otherwise it will fail.

For ease of convenience, there is also a generate_docs.sh script located in the docs directory.

After a successful generation the resulting documentation pages will be located in docs/_build/html directory.

Link checking

To check whether all URLs in the documentation are valid, there exists a make target to automatically check the links:

make checklinks

Note

Run this in the docs directory while in the venv.

This will check whether all the URLs in the documentation are still valid and open a working webpage. Any broken links will be shown in red and also listed in the _build/linkcheck/output.txt file.

Docker

There also exists a Docker file to generate the documentation. To generate this documentation using Docker, in the root directory of the repository run:

docker build -o <output_location> -f GenerateDocumentation.Dockerfile .

This will run the whole documentation generation script and place the generated HTML in the specified directory.

More information

For more information about how to set up and write the documentation, check out the MyriadRF Handbook.