Module bpaf::doc

Documentation generation system

Command line parser documentation generation

OptionParser implements two methods: render_html and render_manpage that create a documentation in a mix of html/markdown and ROFF formats respectively.

To use it you should do something like this

#[test]
fn update_doc() {
    let options = options();
    let md = options.render_markdown("app_name");
    let roff = options.render_manpage("app_name", Section::General, None, None, None);
    // then save those docs into a files
    // If you commit those docs into your repo and optionally fail a test if there
    // are changes - CI will ensure that documentation is always up to date
}

Documentation fragments to use inside --help messages

bpaf tries to use semantic approach to documentation generation, instead of describing what color specific string slice should be you need to specify what this string slice supposed to mean.

Most of the help related functions take Into<Doc> parameters, normally you would pass one of following things:

1. Ready made Doc - usually with combinatoric API

let mut doc = Doc::default();
doc.emphasis("Usage: ");
doc.literal("my_program");
// do something with it
drop(doc)

2. A string slice - &str can be converted into a fully plain text Doc which is enough for most applications

3. A slice of style value pairs

Combinatoric example

#[derive(Debug, Clone)]
pub struct Options {
    number: u32,
}

pub fn options() -> OptionParser<Options> {
    let number = long("number")
        .help(
            &[
                ("Very", Style::Emphasis),
                (" important argument", Style::Text),
            ][..],
        )
        .argument::<u32>("N");
    construct!(Options { number }).to_options()
}

fn main() {
    println!("{:?}", options().run())
}

Derive example

const ARG: &[(&str, Style)] = &[
    ("Very", Style::Emphasis),
    (" important argument", Style::Text),
];

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
pub struct Options {
    #[bpaf(argument("N"), help(ARG))]
    number: u32,
}

fn main() {
    println!("{:?}", options().run())
}

Output

$ app --help

Usage: app --number=N

Available options:

--number=N

Very important argument

-h, --help

Prints help information

4. A structure from your own crate that can be converted into Doc

Structs

• Doc
  String with styled segments.
• MetaInfo
  Parser metainformation

Enums

• Sectiondocgen
  Manual page section
• Style
  Style of a text fragment inside of Doc