The documentation created here is written in reStructuredTexT and generated using Sphinx via a GitHub action.

reStructured text is similar to Markdown in that it is ASCII formatted text that is mostly human-readable and contains directives that specify how the text should be rendered in HTML, and other output formats.

reStructuredText is more complex than Markdown and allows for much greater flexibility in formatting as well as additional features such as directives that act like variables/macros that are defined once and expanded in place.

The GitHub action rules can be found in .github/workflows/docs.yml

C++ API documentation is generated using Doxygen

Frequently used values that may change can be defined in the conf.py file in the rst_prolog section. The rst_prolog gets including in every .rst file and the variables can be referenced by using the format |VARIABLE_NAME| which will get expanded into the generated text.

Use the docs.sh script in this directory to install required dependencies and build the documentation.

To install all needed dependencies (do this once on your development machine):

./docs.sh install

To generate the documentation, run:

./docs.sh build

To render wiring harnesses only:

./docs.sh wire ./path/to/dir/or/file.yml

If the directories are polluted, and you want a clean slate:

./docs.sh clean

The generated output can be viewed by opening the file docs/_build/html/index.html, or you can run this script to have it open it up for you in your browser:

./docs.sh view

You can also check the validity of all links in all markdown and RST-generated files by running:

./docs.sh check

however, for this to work you must install the lychee tool, as described here: https://github.com/lycheeverse/lychee. Otherwise, validity of links will be checked by CI scripts upon committing changes to the repo.

Parts catalog with links to vendors is generated by a set of custom scripts. The json file with parts definitions and relevant custom scripts are all maintained in docs/purchasing

Wiring assembly documentation is generated using the WireViz tool. All wiring assembly definitions and relevant custom scripts are maintained in docs/wiring.

We use a traceability plugin for Sphinx to generate requirement and test traceability reports.

A traceable item is defined using the .. :item:: <id> keyword.

By defining a traceability relationship in the target (ex. derived requirement :fulfills: <parent requirement id>), and bidirectional link is created between the target and source :item:s. Traceability matrices and charts can be generated based on these linkages.

Over time, we can add additional attributes to the traceable items to trace data such as verification method, status, etc...