`mod formats`

module formats

Functions

fn generate_decoration(ch: char, len: usize) -> String

Generate title decoration string for RST or fence for MD.

Args:

ch:: The character to use.
len:: The length of the decoration required.

Returns:

A string of length len composed entirely of ch.

Traits

trait MdContent

Trait for anything that can be converted to MD directive content.

This is implemented for all IntoInterator<Item = String>, effectively allowing Vec<String> to be converted to MD content lines.

fn get_md_text(self) -> Vec<String>

Implemented for

impl<T> MdContent for T where T: IntoIterator<Item = String>, 

fn get_md_text(self) -> Vec<String>

trait MdDirective

Trait for directives that can be written as MD content

const DEFAULT_FENCE_SIZE: usize

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

Generate MD text with the given fence size.

Implementations must provide a vec of the lines of the content of the item and all its members.

Args:

fence_size:: The size of the fence for the directive. Use the make_fence function to get the actual fence string.
max_visibility:: Include only items with visibility up to the defined level.

Returns:

The MD text for the documentation of the item and its members.

fn make_fence(fence_size: usize) -> String

Make a string for the fences for the directive.

Args:

fence_size:: The size of the fence, must be at least 3.

Returns:

A string of colons of length fence_size.

Panics:

If the fence_size is less than 3.

fn calc_fence_size(items: &[Directive]) -> usize

Calculate the fence size required for the item.

The items are the members of the current item. So, for a struct, these will be the list of its fields, for an enum, the variants, for a module, the items defined in it, etc.

The fence size for the item is 1 + the max fence size of all its members. If it has no members, the fence size is the default fence size. So, the returned value is the minimum fence size required to properly document the item and its members in Markdown.

Args:

items:: Items which are members of the current item.

Returns:

The minimum fence size required to document the item and all its nested items.

fn make_md_header<O: MdOption, D: Display, E: Display>(directive: D, name: E, options: &[O], fence: &str) -> Vec<String>

Make the MD directive header from the directive, name and options.

Args:

directive:: The MD directive to make the header for.
name:: The name of the directive.
options:: The directive options to add.
fence:: The fence to use for the directive.

Returns:

A Vec of the directive’s header lines.

fn make_md_toctree<I: Display, T: Iterator<Item = I>>(fence_size: usize, caption: &str, max_depth: Option<u8>, tree: T) -> Vec<String>

Make a toctree directive for MD documents.

Args:

fence_size:: The fence size for the directive.
caption:: The caption for the toctree.
maxdepth:: The desired maxdepth of the toctree. If None, the :maxdepth: option will not be set.
tree:: The toctree entries.

fn make_md_section(section: &str, fence_size: usize, items: Vec<Directive>, max_visibility: &DirectiveVisibility) -> Vec<String>

fn make_md_list(fence_size: usize, title: &str, items: &[(String, Vec<String>)]) -> Vec<String>

Make an MD list of items.

Args:

fence_size:: The fence size for the list title.
title:: The title for the list.
items:: A vec of item name and content tuples.

Returns:

Lines of MD text for the list, with the title.

fn fence_size(&self) -> usize

Return the fence size required for documenting the item.

The default implementation returns 4, which allows for members with no items to create sections within the docstrings, that do not show up in the toctree.

Implementations may use MdDirective::calc_fence_size to override this, when there are nested items present.

trait MdOption

Trait for MD directive options

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

trait RstContent

Trait for anything that can be converted to RST directive content.

This is implemented for all IntoInterator<Item = String>, effectively allowing Vec<String> to be converted to RST content lines.

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

Implemented for

impl<T> RstContent for T where T: IntoIterator<Item = String>, 

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

trait RstDirective

Trait for directives that can be written as RST content

const INDENT: &'static str

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

Generate RST text with the given level of indentation.

Implementations must provide a vec of the lines of the content of the item and all its members.

Args:

level:: The level of indentation for the content. Use the make_indent and make_content_indent functions to get the actual indentation string.
max_visibility:: Include only items with visibility up to the defined level.

Returns:

The RST text for the documentation of the item and its members.

fn make_indent(level: usize) -> String

Make a string for indenting the directive.

Args:

level:: The level of the indentation.

Returns:

A string that is Self::INDENT repeated level times.

fn make_content_indent(level: usize) -> String

Make a string for indenting the directive’s content and options

Args:

level:: The level of the indentation.

Returns:

A string that is Self::INDENT repeated level + 1 times.

fn make_rst_header<O: RstOption, D: Display, E: Display>(directive: D, name: E, options: &[O], level: usize) -> Vec<String>

Make the RST directive header from the directive, name and options.

Args:

directive:: The RST directive to make the header for.
name:: The name of the directive.
options:: The directive options to add.
level:: The indentation level of the directive.

Returns:

A Vec of the directive’s header lines.

fn make_rst_toctree<I: Display, T: Iterator<Item = I>>(indent: &str, caption: &str, max_depth: Option<u8>, tree: T) -> Vec<String>

Make a toctree directive for RST documents.

Args:

indent:: The indentation for the directive.
caption:: The caption for the toctree.
maxdepth:: The desired maxdepth of the toctree. If None, the :maxdepth: option will not be set.
tree:: The toctree entries.

fn make_rst_section(section: &str, level: usize, items: Vec<Directive>, max_visibility: &DirectiveVisibility) -> Vec<String>

fn make_rst_list(indent: &str, title: &str, items: &[(String, Vec<String>)]) -> Vec<String>

Make an RST list of items.

Args:

indent:: The indentation for the list items.
title:: The title for the list.
items:: A vec of item name and content tuples.

Returns:

Lines of RST text for the list, with the title.

trait RstOption

Trait for RST directive options

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

Enums

enum Format

Supported formats for the docstrings

Md: Markdown format

Rst: reStructuredText format

Variables

const MD_VALUES: [&'static str; 3]

const RST_VALUES: [&'static str; 3]

Functions

fn extension(&self) -> &'static str: Returns the extension for the format, without the leading “.”.

fn format_directive<T>(&self, directive: T, max_visibility: &DirectiveVisibility) -> Vec<String> where T: RstDirective + MdDirective, 

Get format specific content for the directive for the output file.

The function assumes that the directive is the top level directive of the output file and generates the content accordingly.

Args:

directive:: The directive to get the content for, typically a Crate or Module directive.

Returns:

A vec of strings which are the lines of the document.

fn make_inline_code<D: Display>(&self, text: D) -> String: Convert the provided text to an inline code representation of the text specific to the format.

fn make_title(&self, title: &str) -> Vec<String>: Make a format specific document title using the provided title string.

Traits implemented

impl FromStr for Format

type Err

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

Parses the string into an enum value, or panics.

If the string is md, .md or markdown, the function returns Md. If the string is rst, .rst or restructuredtext, the function returns Rst. Comparison is case-insensitive.

Args:

value:: The value to parse.

Returns:

The parsed enum value as the Ok value, or unit type as the Err.

mod formats

`mod formats`