Rust specific roles

The extension provides the following docutils roles, which can be referenced as {<role_name>}`<target>` in Markdown and as :<role_name>:`target` in reStructuredText.

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>.

To link to an implementation of a trait by a struct or enum, the target is provided as <crate_name>::<module_path>::<item>::<trait_name>::<trait_item>.

Tip

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.

Role targets within docstrings

When writing docstrings, targets can be specified relative to the module and its imports.

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, without the need for a preceding ~.

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. In this case, the link text will be <enum>::<variant>. A ~ can be added here to display only <variant> as the link text.

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

Markdown docstrings and intra-doc links

The tool supports rustdoc’s Intra-doc links and targets may be referenced in the markdown docstrings directly using [<target>] or [`<target>`]. This feature also works in docs besides docstrings, but the target must be an absolute path. Literal text enclosed within brackets must be escaped using backslash (e.g. \[not a link]) otherwise it will appear as a broken link.

reStructuredText and intra-doc links

Behaviour similar to Markdown Intra-doc links links can be enabled by adding the rust:any as the default_role in Sphinx’s conf.py. With this, items can be linked simply with `<target>` even outside the docstrings.

Provided roles

:rust:any:

:rust:any:`<target>` finds any 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.