Including the docs in the Sphinx build

The sphinx-rustdocgen application generates one document for each source file in the crate. The generated documents are stored in <rust_doc_dir>/<crate_name> directory. The extension does not generate a “cover page” or provide a directive to generate one, and the users have to determine how best they want to structure their docs. Various ways to link the individual documents, items and

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|md> instead of <rust_doc_dir>/crate/module/mod.<rst|md>.

For files that compile to an executable (like main.rs), the documentation is placed in a file with the same name as the executable under the output directory. Within the file, there is a generated table of contents for any modules declared in the executable itself.

For the library modules, the documentation is extracted for all items, except test modules. The documentation for the lib.rs file contains a table of contents that links to the other modules within the library.

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

Via the toctree

The simplest way to include the documentation is to add the crate and executable 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 the documents for the other executables (like crates/my_crate/bin/<executable>) to the toctree entries as well.

Do not use glob patterns with the generated documentation since the necessary toctree directives are already included in the relevant docs. Only the doc for each executable and the crate itself should be included in the toctree.

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.

Including in other docs

It may be preferred to include the generated content in other documents, specially when there is only one executable. The Sphinx include directive can be used for this, like :::{include} path/to/file.md::: or .. include:: path/to/file.rst. Note that the path must include the extension of the document here and must be relative to the file it is included in. As with the toctree method, only the crate or executable documents should be included.

The main gotcha here is the use of titles in the generated documentation. The generated documentation uses = as the title decoration character and adds it both on the top and bottom of the title. As long as there is no conflict with this decoration in the document, the documentation will be generated properly.

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 or included in a hidden toctree.

Linking directly to Rust items

The various roles described in Rust specific roles can be used to link directly to an item. Using these, the documentation can be organized in tables, lists, paragraphs or any other structure supported by Sphinx.

When using this method, a hidden toctree should be generated for the documents of the executable and crate to ensure that Sphinx can discover all documents properly.