Rust specific directives

The extension adds the directives listed here, that are used by the sphinx-rustdocgen documentation in its output and can also be used to manually write documentation for Rust items. All directives can have content and can be nested under each other for structuring the documentation.

All directives take the following options:

vis:

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

sig:

(Optional) The signature of the directive to display in the content. By default, this is the item type and the identifier of the item, along with any generics.

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.

type:

(Optional) Used mainly for variables to specify the type of the variable.

no-index:

(Optional) A flag to indicate the directive should not be indexed.

crate

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

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.

function

The .. rust:function:: <fn_path> directive documents a function. The function may be n 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.

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.

macro

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

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.

struct

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

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

trait

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

type

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

variable

The .. rust:variable:: <variable_path> directive documents a static or const 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.