Rust specific roles

The extension provides the following docutils roles, which can be referenced as :<role_name>:.

Role target specification

For all roles, the target is the double colon (::) delimited full Rust path to the item, similar to the path used when importing the item. This syntax is slightly extended to accommodate linking to trait impl blocks and fields within a struct.

For all importable items like structs, enums, traits, etc., the target path is the Rust import path, either <crate_name>::<module_path>::<item> or <executable_name>::<module_path>::<item>. For referencing implementations of a trait or items within a trait impl, the link target is provided as <crate_name>::<module_path>::<item>::<trait_name>::<trait_item>.

Adding a ~ before the path will display only the final portion of the path as the link text. So, :rust:fn:`~crate::module::func` will display only func as the link text. This is generally used when linking to an item from outside the source code.

Role targets within source code

When the role is used within the Rust source code, any items defined or imported in the same file with a use statement may be referenced directly. So, :rust:struct:`Foo` will link to a struct Foo defined or imported within that file. This makes the references within the docstrings much shorter and the docstrings easier to read. The text for the link will be Foo in this case.

The short reference can also be used for items that are members of or associated with an defined or imported item. For example, a variant of an enum defined within the file can be referenced as :rust:struct:`<enum>::<variant>` within the file itself.

Short references are not supported for items that are imported as part of a glob (*) import.

Details for individual roles are described below.

:rust:any:

:rust:any:`<target>` finds an item that matches the target and links to it. This is similar to Sphinx’s any role, but within the Rust domain. Use this role as the default role for the build to reference Rust items without any role specified.

:rust:crate:

:rust:crate:`<crate_name>` links to the crate’s documentation, within lib.rs.

:rust:enum:

:rust:enum:`<enum_path>` links to an enum’s documentation. Specific variant’s within the enum can be referenced

using the struct role.

:rust:exe:

:rust:exe:`<executable_name>` links to an executable’s documentation.

:rust:executable:

Alias for rust:exe.

:rust:fn:

:rust:fn:`<fn_path>` links to a function’s documentation.

To a reference an associated function, use the full path to the impl block where the function is defined, followed by the function’s name. See the rust:impl documentation below for details.

Note that the path <trait_path>::<fn> references the function declaration within the trait, whereas <struct_path>::<trait>::<fn> references the implementation of the trait’s function for the struct.

:rust:function:

Alias for rust:fn.

:rust:impl:

:rust:impl:`<impl_path>` links to an impl block, either of the struct, or for a trait for a struct. The <impl_path> is provided as <crate_name>::<module_name>::<item> for struct or enum impl blocks and as <crate_name>::<module_name>::<item>::<trait_name> for trait impl blocks.

When referencing an impl block for a struct or an enum, use the full path to the impl block within the crate. So, if the impl Foo block is in a different module from the struct itself, the path must reference the module of the impl block. Items within the impl block like functions and variables are then nested under this path.

When referencing a trait impl block, the last two components of the path are <item>::<trait>. So, a block impl Display for Foo is referenced as crate::module::Foo::Display.

:rust:macro:

:rust:macro:`<macro_path>` inks to a macro’s documentation.

:rust:module:

:rust:module:`<module_path>` inks to the module’s documentation. The module path here is the Rust path of the

module, not its file’s path. So, even if the module is defined in a mod.rs file, the path here will be the path to import the module in a use statement.

:rust:struct:

:rust:struct:`<struct_path>` links to a struct or an enum variant’s documentation. For an enum variant, use :rust:struct:`<enum_path>::<variant>` as the target.

Specific fields within the struct or variant can be referenced using the rust:variable role.

:rust:trait:

:rust:trait:`<trait_path>` links to a trait’s documentation. Items defined within the trait are nested under the trait’s path.

:rust:type:

:rust:type:`<type_path>` links to a type’s documentation.

:rust:variable:

:rust:variable:`<variable_path>` links to a static or const variable, or to a field within a struct or enum variant.

For fields of a struct, the path is <struct_path>::<field_name>.

For tuple structs, the field’s index should be used instead of the name (<struct_path>::0).

For an enum variant’s fields, the path is <enum_path>::<variant>::<field_name>, with field index instead of name for tuple variants.

:rust:var:

Alias for rust:variable.