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.

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 > ,) -> (Vec < ModuleDirective > , Vec < (& 'static str , Vec < Directive >) >)

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)
Function(FunctionDirective)
Impl(ImplDirective)
Macro(MacroDirective)
Module(ModuleDirective)
Struct(StructDirective)
Trait(TraitDirective)
Type(TypeDirective)
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.

NoIndex

The :no-index: option

Vis(DirectiveVisibility)

The :vis: option.

Sig(String)

The :sig: option.

Toc(String)

The :toc: option.

Type(String)

The :type: 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

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.

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) -> String
impl RstOption for DirectiveOption
fn get_rst_text (& self , indent : & str) -> 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 >

Modules