Metadata-Version: 2.1
Name: sphinxcontrib-rust
Version: 0.1.1
Summary: Sphinx extension for documenting Rust projects
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Domain
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Rust
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.9
Description-Content-Type: text/plain
License-File: LICENSE
Requires-Dist: sphinx <8,>=7
Provides-Extra: dev
Requires-Dist: beautifulsoup4 ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Requires-Dist: lxml ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme ; extra == 'dev'

==================
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 :doc:`TODO`.

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

You can read this documentation on `Gitlab Pages`_ or `readthedocs`_.

.. _`Gitlab Pages`: https://sphinxcontrib-rust-mmc691-8fb22cc6152ca3a233f41dbc6179d6a5fd539.gitlab.io/

.. _`readthedocs`: https://sphinxcontrib-rust.readthedocs.io/en/latest/

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:

1. Rust specific directives and roles that can be used to link and
   cross-reference rustdoc comments.

2. rustdoc comments may be written in reStructuredText. (This
   might break IDE and other integrations that expect Markdown).

.. _`usage`:

How to use
----------

Installation
++++++++++++

There are two components that are required for this to work

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

Both components are installed when installing the Python package with

.. code-block::

   pip install sphinxcontrib-rust

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

Make sure that the path where ``cargo`` installs the executable is in
``$PATH`` as well. The executable is used during the Sphinx build.

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.

.. code-block:: python

   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
:doc:`docs/including` for more details.

.. code-block::

   .. 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 are documented in :doc:`docs/roles`.

The extension also provides various :doc:`docs/directives` and
:doc:`docs/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.

.. code-block:: python

   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: A dict of crate names and their source code directories.
:rust_doc_dir: 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_rustdoc_fmt: Either ``"rst"`` or ``"md"``.
                   (Default: ``"rst"``, but likely to change once stable).
:rust_visibilty: 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"``).

.. _`Sphinx`: https://www.sphinx-doc.org/en/master/index.html
.. _`myst-parser`: https://myst-parser.readthedocs.io/en/latest/index.html
.. _`configured for Markdown builds`: https://www.sphinx-doc.org/en/master/usage/markdown.html
.. _`configuration options for MyST`: https://myst-parser.readthedocs.io/en/latest/configuration.html
.. _`myst-parser syntax`:
   https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-an-in-line-extension-point

.. _details:

.. toctree::
   :caption: Detailed docs
   :maxdepth: 2
   :glob:

   docs/including
   docs/roles
   docs/directives
   docs/indices
   docs/sphinx-rustdocgen
   docs/sphinx-extension
   TODO
