Documentation

This doc details the structures and procedures used when writing documentation in and for Kubos products.

Please refer to the Kubos standards doc for more detailed documentation standards regarding things like naming and grammar.

Generating The Docs

The Kubos docs are generated using Sphinx in conjunction with a variety of tools including rustdoc and Doxygen. We suggest generating the docs from inside of the Kubos SDK environment, as it already has all dependencies installed.

If you would like to generate the docs outside of the SDK environment, please refer to the following list of dependencies, in addition to the list of build dependencies.

System dependencies:

  • doxygen
  • graphvis
  • plantuml
  • Python 3 + pip3

Python dependencies (most likely installed with pip3):

  • Sphinx v1.5.6
  • breathe v4.12.0
  • sphinx-rtd-theme v0.2.4
  • sphinxcontrib-plantuml
  • sphinxcontrib-versioning
  • sphinx-jsondomain

In order to generate the entirety of the documentation locally, navigate to the top level of your copy of the Kubos repo and run tools/docs/gendocs.py.

The generated HTML files will be in the html folder, which you can then use to verify your new docs display as intended.

To verify your docs:

  • Make sure that any new *.rst files are accessible through normal page clicks if you start at the top-level index.html
  • Verify that any new hyperlinks work as intended
  • Make sure that tools/docs/gendocs.py runs successfully without throwing any errors or warnings. Fix all warnings until the script runs cleanly.

General Docs

All docs files under docs/ are written in the reStructuredText format. Please refer to the standards doc for more specific writing standards.

All executable projects, such as clients, examples, or services, should have a README.md which explains the purpose of the project, basic usage, and any runtime configuration options.

Documenting Rust

The Rust book provides a pretty good overview of the standards for documenting Rust code here.

We leverage the cargo doc tool in generating our Rust documentation, so all Rust source is expected to conform to the standards laid out in the book.

Documentation for any individual crate can be generated by running cargo doc from within that crate’s folder. The generated docs can be found in kubos/target/doc/<crate-name>.

Including Rust Docs

The Rust docs generated by cargo doc will be placed in kubos/target/doc/<crate-name>. These files are not accessible to the rest of the docs, so the contents of kubos/target/doc are moved to html/rust_docs during the documentation generation process.

Adding a reference to the Rust docs just means adding a link to the appropriate html file:

This example references the |docs| for the file service.

.. |docs| raw:: html

    <a href="../rust-docs/file_service/index.html" target="_blank">docs</a>

Documenting Python

The Python source in the Kubos repo follows the PEP 257 docstring conventions.

Public facing functions, classes, and modules should all be documented with the appropriate, descriptive docstrings.

Including Python Docs

Any new python modules will need to be added to the python_modules list in docs/conf.py file so that Sphinx picks them up in the docs generation process.

Documenting C

Within the new modules’s folder, create a docs subfolder and add a Doxyfile file. Feel free to copy Doxyfile from another C module, just change the PROJECT_NAME value.

Within each header file of the module, add the following block to the top of the file in order for Doxygen to be able to process it:

/**
 * @defgroup <project-name> <Module description>
 * @addtogroup <project-name>
 * @{
 */

And then add this to the bottom of the file:

/* @} */

Within the header files, all items should be documented using Doxygen’s formatting.

Including C Docs

To include the new files in doc generation:

  • Add an entry to breathe_projects in docs/conf.py
  • Add an entry to DOCS_DIRS in tools/docs/gendocs.py

The <new-module>.rst doc should contain the declarations needed for the module documentation generated by Doxygen to be picked up and included in the final HTML:

.. doxygenfile:: module-header.h
    :project: module-name