`mod formats`

module formats

Module for handling the output formats supported.

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 IntoIterator<Item = String>, effectively allowing Vec<String> to be converted to MD content lines.

Functions

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

Implemented for

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

Functions

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

trait MdDirective

Trait for directives that can be written as MD content

Variables

const DEFAULT_FENCE_SIZE: usize

Functions

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

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 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_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 make_md_section(section: &str, fence_size: usize, items: Vec<Directive>, max_visibility: &DirectiveVisibility) -> Vec<String>

Make section in an MD document with the given title and items.

Args:

section:: The title of the section.
fence_size:: The fence size of the section.
items:: The items to include in the section.
max_visibility:: The max visibility of the items to include.

Returns:

The MD text for the section.

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.

trait MdOption

Trait for MD directive options

Functions

fn get_md_text(&self) -> Option<String>: Return the MD text for the option.

trait RstContent

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

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

Functions

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

Implemented for

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

Functions

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

trait RstDirective

Trait for directives that can be written as RST content

Variables

const INDENT: &'static str

Functions

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

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

Make section in an RST document with the given title and items.

Args:

section:: The title of the section.
level:: The indentation level of the section.
items:: The items to include in the section.
max_visibility:: The max visibility of the items to include.

Returns:

The RST text for the section.

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.

trait RstOption

Trait for RST directive options.

Functions

fn get_rst_text(&self, indent: &str) -> Option<String>: Return the RST text for the option.

Enums

enum Format

Supported formats for the docstrings

Md: Markdown format

Rst: reStructuredText format

Implementations

impl Format

Variables

const MD_VALUES: [&'static str; 3]: Acceptable text values for Md variant, case-insensitive.

const RST_VALUES: [&'static str; 3]: Acceptable text values for Rst variant, case-insensitive.

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

Types

type Err

Functions

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`