Sphinxcontrib-rust

Warning

This project is still under development. While basic features are available, there are still improvements to make. Some limitations can be checked from reading the TODO list.

This is a Sphinx extension for integrating Rust programming language projects in Sphinx builds.

You can read this documentation on Gitlab Pages or readthedocs.

Motivation

This is primarily meant for teams and projects that are already using Sphinx as a documentation build tool, and would like to include documentation for Rust projects in it along with Python, C and other languages.

Using the extension adds the following functionality:

Rust specific directives and roles that can be used to link and cross-reference rustdoc comments.
rustdoc comments may be written in reStructuredText. (This might break IDE and other integrations that expect Markdown).

How to use

Installation

There are two components that are required for this to work

The sphinx-rustdocgen Rust crate for extracting the docs.
The sphinxcontrib_rust Python package, which is a Sphinx extension.

Both components are installed when installing the Python package with

pip install sphinxcontrib-rust

The installation will check for cargo in the $PATH environment variable and will use that to build and install the Rust executable.

The executable is built with the Rust code shipped with the Python package. This ensures that the Rust executable and Python package are always compatible with each other.

Make sure that the path where cargo installs the executable is in $PATH as well. If the default installation directory is not part of the $PATH environment, the installed executable should be specified in the Sphinx configuration with rust_rustdocgen option.

The Rust executable may also be installed independently from crates.io or built with the shipped source code.

With reStructuredText

To use the extension with rst rustdoc comments, simply add the extension to the conf.py file. The various configuration options supported by the extension, along with their defaults, are documented below.

extensions = ["sphinxcontrib_rust"]
rust_crates = {
    "my_crate": "src/",
    "my_crate_derive": "my-crate-derive/src",
}
rust_doc_dir = "docs/crates/"

This will generate the documentation from your Rust crates and put them in the docs/crates/<crate_name> directories. You can link against the documentation in your toctree by specifying the path to the main or lib file. See Including the docs in the Sphinx build for more details.

.. toctree::

   docs/crates/my_crate/main
   docs/crates/my_crate/lib

The extension also adds various roles for Rust items. The roles can be used within the Sphinx documentation and also within the docstrings themselves. The roles can even be used in docstrings of a different language that is part of the same Sphinx project. The roles are documented in Rust specific roles.

The extension also provides various Rust specific directives and Rust specific indices that can be used in the documentation.

With Markdown

This feature is still a work in progress, and needs more tests, but the aim is to allow for a simpler transition to Sphinx without rewriting the comments in reStructuredText.

To use the extension with the standard markdown rustdoc comments, add the extension to the conf.py file and also add the myst-parser extension. Sphinx also needs to be configured for Markdown builds.

The various configuration options for the Rust extension, along with their defaults, are documented below. Also see the configuration options for MyST to customize the markdown.

extensions = ["sphinxcontrib_rust", "myst_parser"]
source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
    ".txt": "markdown", # Optional
}
myst_enable_extensions = {
    "colon_fence",
}
myst_ref_domains = [
    "rust",
]
rust_crates = {
    "my_crate": "src/",
    "my_crate_derive": "my-crate-derive/src",
}
rust_doc_dir = "docs/crates/"

Note that myst-parser has to be installed as dependency to the Sphinx build from PyPI with pip install myst-parser or by specifying it as a dependency in setup.py or pyproject.toml of the project.

This enables all the same roles and indexes as with rst. Use the myst-parser syntax for the roles.

Options

Options are simply Python variables set in the conf.py file.

rust_crates:: (Required) A dict of crate names and their source code directories.
rust_doc_dir:: (Required) The directory under which to write the docs. Must be a directory that will be read by Sphinx and not under the build directory.
rust_rustdocgen:: The path to the sphinx-rustdocgen executable to use. The path must be an absolute path or relative to Sphinx’s working directory. (Default: Obtained from the $PATH environment variable.)
rust_no_generate:: Do not scan the crate and generate documents. Useful for testing with existing docs. (Default: False)
rust_rustdoc_fmt:: Either rst or md. (Default: rst)
rust_visibility:: Only includes documentation and indexes for items with visibility greater than or equal to the setting. The value can be pub, crate or pvt. Visibility restrictions like super and in <path> are not supported currently and are treated as private. (Default: pub).