Developer Documentation

The project consists of 3 main components:

The sphinx-rustdocgen crate for extracting and formatting the documentation comments from Rust code.
The sphinxcontrib_rust Sphinx extension for parsing the output of the executable.
Project documentation and CI for testing and maintaining.

Rust crate

The Rust crate has two main modules, sphinx-rustdocgen::formats and sphinx-rustdocgen::directives.

The formats module consists of various traits that implement formatting the output as reStructuredText or Markdown. Most code related to formatting the details of a directive lives in this module.

The directives module and its submodules implement the Rust side of all the Rust specific directives. The Directive enum is where new directives should be added first. Each variant of this enum is a newtype for a struct that holds the details of the directive. The structs must implement both sphinx-rustdocgen::formats::RstDirective and sphinx-rustdocgen::formats:MdDirective traits. Take a look at one of the existing directive implementation for an example.

Sphinx extension

The Sphinx extension is largely dedicated to reading the directive and converting them to content.

The directives are defined in sphinxcontrib_rust.directives. All the directives inherit from the sphinxcontrib_rust.directives.RustDirective class, which handles the options and converts them into the directive’s display text.

The Sphinx domain itself is implemented in sphinxcontrib_rust.domain module. The domain mostly just manages the directives for referencing and indexing.

The __init__.py file of the package is the interface for Sphinx to connect with the extension and for the extension to execute the Rust executable to generate the pages.

Docs and CI

The CI for the project makes sure that the Rust and Python code are properly formatted and linted as per the Styleguides.

It will first test the Rust crate and then the Sphinx extension. As part of the test, the project will run on itself. It will also ensure that the Python package can be built and the documentation is generated properly for readthedocs.org and for GitLab pages.