bpaf/
doc.rs

1//! Documentation generation system
2//!
3//! # Command line parser documentation generation
4//!
5//! [`OptionParser`] implements two methods: [`render_html`](OptionParser::render_html) and
6//! [`render_manpage`](OptionParser::render_manpage) that create a documentation in a mix of
7//! html/markdown and ROFF formats respectively.
8//!
9//! To use it you should do something like this
10//! ```
11//! #[test]
12//! fn update_doc() {
13//!     # use bpaf::*;
14//!     # let options = || short('a').switch().to_options();
15//!     let options = options();
16//!     let md = options.render_markdown("app_name");
17//!     let roff = options.render_manpage("app_name", Section::General, None, None, None);
18//!     # drop(md); drop(roff);
19//!     // then save those docs into a files
20//!     // If you commit those docs into your repo and optionally fail a test if there
21//!     // are changes - CI will ensure that documentation is always up to date
22//! }
23//! ```
24//!
25//! # Documentation fragments to use inside `--help` messages
26//!
27//! `bpaf` tries to use semantic approach to documentation generation, instead of describing what
28//! color specific string slice should be you need to specify what this string slice supposed to
29//! mean.
30//!
31//! Most of the help related functions take `Into<Doc>` parameters, normally you would pass one of
32//! following things:
33//!
34//! 1. Ready made `Doc` - usually with combinatoric API
35//! ```ignore
36//! # use bpaf::doc::Doc;
37//! let mut doc = Doc::default();
38//! doc.emphasis("Usage: ");
39//! doc.literal("my_program"); // or use `env!("CARGO_BIN_NAME")` to get the name of the executable
40//! // do something with it
41//! drop(doc)
42//! ```
43//! 2. A string slice - `&str` can be converted into a fully plain text `Doc` which is enough
44//!    for most applications
45//!
46//! 3. A slice of style value pairs
47#![cfg_attr(not(doctest), doc = include_str!("docs2/help.md"))]
48//!
49//! 4. A structure from your own crate that can be converted into `Doc`
50//!
51
52#[doc(inline)]
53pub use crate::buffer::{Doc, MetaInfo, Style};
54
55#[doc(inline)]
56#[cfg(feature = "docgen")]
57pub use crate::buffer::Section;
58
59#[cfg(doc)]
60use crate::*;