Including the docs in the Sphinx build

The sphinx-rustdocgen documentation application generates one document for each file in the crate. The generated documents are stored in <rust_doc_dir>/<crate_name> directory.

The generated documentation is organized similar to the crate, except that src/module/mod.rs files are documented as <rust_doc_dir>/crate/module.rst instead of <rust_doc_dir/crate/module/mod.rst.

For the main.rs file, only the documentation for the file itself is extracted, and placed in <rust_doc_dir>/<crate_name>/main.rst. For the lib.rs file and all other modules, the documentation is extracted for all items, except test modules. These files also contain toctree directives that mimic the Rust module structure.

The generated documents can be linked with the toctree, included in other docs and referenced using the :doc: role in Sphinx.

Note

The documentation here uses .rst as the extension in examples, but the same holds for Markdown files with .md extension.

Via the toctree

The simplest way to include the documentation is to add the lib and main docs in a toctree directive. This will automatically add the other documents to the toctree also.

.. toctree::
   :glob:

   some_doc
   crates/my_crate/main
   crates/my_crate/lib
   other_docs/*

If the crate has multiple executables, add crates/my_crate/bin/* to the toctree entries as well. Do not use glob patterns (crates/my_crate/*) for the remaining documentation since the necessary toctree directives are already included in the lib doc and other module’s docs.

The path in the toctree must be relative to the document in which the toctree is or an absolute path rooted in the Sphinx source directory.

As included doc

It may be preferred to include the generated document in other documents, specially for the main doc. The Sphinx .. include:: path/to/file.rst does this. In case Sphinx warns about files not included in the toctree, the file can be added to the exclude_patterns list in the Sphinx configuration.

To create single entry point for the crate similar to Rustdoc’s output, add the toctree directive for the lib file within the main.rs comment like.

//! My crate's executable
//!
//! Usage: ``foo <options> <file>``
//!
//! .. toctree::
//!
//!    /<rust_doc_dir>/my_crate/lib

Now, including the main doc in another doc, like the README or index file, will create an entrypoint into the crate’s documentation from the home page itself. Using the absolute path from the Sphinx’s source directory here makes sure that link works no matter where the main doc included.

This project uses this method for including the docs in the Sphinx build.

Linking to a document

This is generally not necessary and the Rust specific roles should be preferred instead of this, but Sphinx’s :doc: role can be used with the document path without the extension as the target.