mod directives

module directives

Module for the various Sphinx directives for the Rust domain.

The module primarily provides the Directive, which implements the various directives using directive specific structs. The enum and all directive specific structs implement both RstContent and MdContent traits. It also provides the DirectiveOption enum, which implements the various options of the directive.

The output of the directives is parsed by the sphinxcontrib_rust.directives.RustDirective within the Python extension.

Modules

• mod crate_directive
• mod enum_directive
• mod executable_directive
• mod foreign_mod
• mod function_directive
• mod impl_directive
• mod macro_directive
• mod module_directive
• mod struct_directive
• mod trait_directive
• mod type_directive
• mod use_directive
• mod variable_directive

Types

type DocStructure

Named tuple type for the output of order_items.

The elements are:

• The list of the modules that should be added to toctree.

• The list of document section titles and the directives within them.

• The list of use directives to include within the document.

Macros

macro check_visibility

Check the options to determine if the visibility of a directive matches the specified max visibility and return empty Vec if not.

This macro should be used within a function and will cause it to return early when the visibility of the options provided does not meet the specified max.

Args:

options:

A vec of DirectiveOption

max:

The maximum visibility that should be included in the output.

macro push_sorted

macro visibility_to_inherit

DRY macro to check which visibility value to pass to inner items.

Functions

fn extract_doc_from_attrs(attrs: &Vec<Attribute>) -> Vec<String>

Extract the docstring from the attrs of an item.

Args:

attrs:

syn::attr::Attribute vec.

Returns:

A vec of strings, where each string is a line of a documentation comment. If there are no documentation comments, an empty vec is returned.

fn order_items(items: Vec<Directive>) -> DocStructure

Order the items for documentation

The items are ordered using the following rules:

1. If the item is a module without content, it is removed and a link to the module is added to the toctree. If there are no such module, the toctree isn’t added.

2. Each directive is then separated by type and ordered alphabetically except for impl directives.

3. All impl blocks associated with a struct or enum are ordered after it, starting with the associated impl block, followed by trait impl blocks in alphabetical order.

Returns:

An vec of module directives that have no items and a vec of section names with their directives.

Enums

enum Directive

The Sphinx directives that are implemented by the Rust domain.

Crate(CrateDirective)

Enum(EnumDirective)

Executable(ExecutableDirective)

ForeignMod(ForeignModDirective)

Function(FunctionDirective)

Impl(ImplDirective)

Macro(MacroDirective)

Module(ModuleDirective)

Struct(StructDirective)

Trait(TraitDirective)

Type(TypeDirective)

Use(UseDirective)

Variable(VariableDirective)

enum DirectiveOption

Enum to represent the various options for the directives.

The enum implements the RstContent and MdContent traits for easily converting the options to required text.

Index(IndexEntryType)

The :index: option

Vis(DirectiveVisibility)

The :vis: option.

Layout(Vec<Node>)

The :layout: option.

Toc(String)

The :toc: option.

enum DirectiveVisibility

Enum for the values of the Vis option

The enum is ordered Pub < Crate < Pvt, so it can be efficiently compared for filtering. Note that ordering here is opposite to that of the visibility itself.

Pub

Crate

Pvt

enum IndexEntryType

The different index entry types.

This corresponds to the Python enum sphinxcontrib_rust.items.SphinxIndexEntryType.

None

Normal

WithSubEntries

SubEntry

Impls

impl Directive

fn name(&self) -> &str

fn from_item(parent_path: &str, item: &Item, inherited_visibility: &Option<&Visibility>) -> Option<Directive>

Create the appropriate directive from the provided syn::Item

Args:

parent_path:

The parent path of the item.

item:

The item to parse into a directive.

Returns:

An option a sphinx-rustdocgen::directives::Directive variant.

fn from_items<'a, T: Iterator<Item = &'a Item>>(parent_path: &str, items: T, inherited_visibility: &Option<&Visibility>) -> Vec<Directive>

Create the appropriate directives from the provided syn::Item iterator.

Args:

parent_path:

The parent path of the items.

items:

The items to parse into a directive.

Returns:

An vec of sphinx-rustdocgen::directives::Directive variants.

fn from_impl_item(parent_path: &str, item: &ImplItem, inherited_visibility: &Option<&Visibility>) -> Option<Directive>

Create the appropriate directive from the provided syn::ImplItem

Args:

parent_path:

The path of the impl block which defines the item.

item:

The impl item to parse into a directive.

Returns:

An option a sphinx-rustdocgen::directives::Directive variant.

fn from_impl_items<'a, T: Iterator<Item = &'a ImplItem>>(parent_path: &str, items: T, inherited_visibility: &Option<&Visibility>) -> Vec<Directive>

Create the appropriate directives from the provided syn::ImplItem iterator.

Args:

parent_path:

The path of the impl block which defines the items.

items:

The impl items to parse into a directive.

Returns:

An vec of sphinx-rustdocgen::directives::Directive variants.

fn from_trait_item(parent_path: &str, item: &TraitItem, inherited_visibility: &Option<&Visibility>) -> Option<Directive>

Create the appropriate directive from the provided syn::TraitItem

Args:

parent_path:

The path of the trait which defines the items.

item:

The trait item to parse into a directive.

Returns:

An option a sphinx-rustdocgen::directives::Directive variant.

fn from_trait_items<'a, T: Iterator<Item = &'a TraitItem>>(parent_path: &str, items: T, inherited_visibility: &Option<&Visibility>) -> Vec<Directive>

Create the appropriate directives from the provided syn::TraitItem iterator.

Args:

parent_path:

The path of the trait which defines the items.

items:

The trait items to parse into a directive.

Returns:

An vec of sphinx-rustdocgen::directives::Directive variants.

fn from_extern_item(parent_path: &str, item: &ForeignItem, inherited_visibility: &Option<&Visibility>) -> Option<Directive>

fn from_extern_items<'a, T: Iterator<Item = &'a ForeignItem>>(parent_path: &str, items: T, inherited_visibility: &Option<&Visibility>) -> Vec<Directive>

impl Display for Directive

fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result

impl MdDirective for Directive

fn get_md_text(self, fence_size: usize, max_visibility: &DirectiveVisibility) -> Vec<String>

fn fence_size(&self) -> usize

impl RstDirective for Directive

fn get_rst_text(self, level: usize, max_visibility: &DirectiveVisibility) -> Vec<String>

impl MdOption for DirectiveOption

fn get_md_text(&self) -> Option<String>

impl RstOption for DirectiveOption

fn get_rst_text(&self, indent: &str) -> Option<String>

impl DirectiveVisibility

fn effective_visibility(visibility: &Visibility, inherited_visibility: &Option<&Visibility>) -> DirectiveVisibility

impl Display for DirectiveVisibility

fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result

impl FromStr for DirectiveVisibility

type Err

fn from_str(s: &str) -> Result<Self, Self::Err>