Rust specific directives

The extension adds the directives listed here, that are used by the sphinx-rustdocgen in its output. All directives, rust:use, can have content and can be nested under them for structuring the documentation. See the documentation for the individual directives, if defining them manually in a document. However, that is not a recommended use and the directives are designed for programmatic creation and manipulation.

All directives, except rust:use, take the following options:

index:

(Required) A integer that indicates the type of the index. See sphinxcontrib_rust.items.SphinxIndexEntryType or sphinx_rustdocgen::directives::IndexEntryType for values.

vis:

(Required) The visibility of the directive, pub, crate or pvt.

layout:

(Optional) A JSON list of sphinxcontrib_rust.nodes.Node objects. Currently, the JSON must be entirely on one line. If not provided, the directives signature will be rendered as the item type in a keyword node and the last segment of the directive item’s path as the name.

toc:

(Optional) The signature of the directive to display in the toctree. By default, this is the item type and the identifier of the item.

.. rust:crate::

The .. rust:crate:: <crate_name> directive documents the crate itself, using the documentation from the lib.rs file.

.. rust:enum::

The .. rust:enum:: <enum_path> directive documents an enum. To document individual variants, use the struct directive and nest it under the enum directive.

.. rust:executable::

The .. rust:executable:: <executable_name> directive documents an executable provided by the crate. Note that the target here is the name of the generated executable, and not a Rust path to the executable. Items within the executable can be referenced with the executable name as the prefix instead of the crate name.

.. rust:function::

The .. rust:function:: <fn_path> directive documents a function. The function may be an associated function of a struct/enum, or part of a trait impl of a struct.

In such cases, the path to the function is <module_path>::<struct_ident>::<fn_ident> or <module_path>::<struct_ident>::<trait_ident>::<fn_ident>. The module_path must be the path of the module in which the impl block is defined.

The function can also be a function declaration within an extern "C" block. In this case, the function is nested directly under the module and the reference path should be <module_path>::<fn_ident>.

.. rust:impl::

The .. rust:impl:: <impl_path> directive documents an impl block. The path here is the <module_path>::<struct_ident> or <module_path>::<struct_ident>::<trait_ident>.

If manually writing the documentation, it is best to organize impl blocks together, with the impl block of the struct/enum first, followed by various trait impls of the struct/enum. Due to the way Sphinx nests items in the toctree, this will display one impl Struct in the toctree and nest the trait impls under it.

If there is no associated impl block and only trait impl blocks for the struct, the trait impl blocks should be after the struct directive so that the impl blocks are nested under the struct itself.

.. rust:macro::

The .. rust:macro:: <marco_path> directive documents a macro.

.. rust:module::

The .. rust:module:: <module_path> directive documents a macro. When the module contains other modules, they can be nested under the parent module’s directive or in a different file, with a link from the parent module.

The sphinx-rustdocgen documentation automatically organizes the module directives based on where the module’s items are defined and places the links in the parent module.

.. rust:struct::

The .. rust:struct:: <struct_path> directive documents a struct, a union or an enum variant. When documenting an enum variant, the path is .. rust:struct::<enum_path>::<variant>.

To document individual fields, use the rust:variable directive and nest it under the struct directive.

.. rust:trait::

The .. rust:trait:: <trait_path> directive documents a trait.

.. rust:type::

The .. rust:type:: <type_path> directive documents a type defined with type T = ... syntax.

The type can also be a type declaration within an extern "C" block. In this case, the type is nested directly under the module and the reference path should be <module_path>::<type_ident>.

.. rust:use::

The .. rust:use:: directive is a meta-directive that has no content. The argument to the directive is a path that is used in the file being processed.

The directive has a required option, used_name, which indicates the name provided by the use path that can be used in references in the same file. The value can be set to self to reference items defined within the document itself.

It also has an optional option, reexport, whose value is the path under which the name is reexported. This is generally the path of the module in which the use statement appears.

This allows using shorter paths for Rust item references within the document itself. Note that this only applies to references, and not directive names.

There can be multiple rust:use directives in a document. If there are conflicts, the last defined mapping is picked.

.. rust:variable::

The .. rust:variable:: <variable_path> directive documents a variable or a field in a struct.

For fields, the path is the <struct_path>::<field_name>. For tuple structs, the field_name is the index of the field within the tuple.

The variable can also be a static variable declaration within an extern "C" block. In this case, the variable is nested directly under the module and the reference path should be <module_path>::<type_ident>.