====================================== Including the docs in the Sphinx build ====================================== The :rust:exe:`sphinx-rustdocgen` application generates one document for each source file in the crate. The generated documents are stored in ``/`` 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 ``/crate/module.`` instead of ``/crate/module/mod.``. 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. .. code-block:: .. 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/``) 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 :doc:`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.