Skip to main content

cornerstone/
docs.rs

1//! Documentation generation. Produces a `man` page (roff) or a Markdown
2//! reference straight from the declared commands — the same specs that drive
3//! help and completion — so a tool's docs never drift from its actual interface.
4//! Exposed through the built-in `docs <man|markdown>` path.
5
6use crate::spec::Command;
7
8/// Output format for generated docs.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub enum DocFormat {
11    Man,
12    Markdown,
13}
14
15impl DocFormat {
16    pub fn parse(s: &str) -> Option<DocFormat> {
17        match s.to_lowercase().as_str() {
18            "man" | "roff" => Some(DocFormat::Man),
19            "markdown" | "md" => Some(DocFormat::Markdown),
20            _ => None,
21        }
22    }
23    pub fn all() -> [&'static str; 2] {
24        ["man", "markdown"]
25    }
26}
27
28/// Generate documentation for the app.
29pub fn generate(
30    app: &str,
31    version: &str,
32    about: &str,
33    commands: &[Command],
34    fmt: DocFormat,
35) -> String {
36    match fmt {
37        DocFormat::Man => man(app, version, about, commands),
38        DocFormat::Markdown => markdown(app, version, about, commands),
39    }
40}
41
42fn man(app: &str, version: &str, about: &str, commands: &[Command]) -> String {
43    let mut out = String::new();
44    out.push_str(&format!(
45        ".TH {} 1 \"\" \"{} {}\" \"User Commands\"\n",
46        app.to_uppercase(),
47        app,
48        version
49    ));
50    out.push_str(".SH NAME\n");
51    out.push_str(&format!("{} \\- {}\n", app, about));
52    out.push_str(".SH SYNOPSIS\n");
53    out.push_str(&format!(".B {}\n[\\fICOMMAND\\fR] [\\fIOPTIONS\\fR]\n", app));
54    out.push_str(".SH COMMANDS\n");
55    for c in commands {
56        man_command(&mut out, app, c, &[]);
57    }
58    out
59}
60
61fn man_command(out: &mut String, app: &str, cmd: &Command, parents: &[&str]) {
62    let path = {
63        let mut p = parents.to_vec();
64        p.push(&cmd.name);
65        p.join(" ")
66    };
67    out.push_str(&format!(".TP\n.B {} {}\n{}\n", app, path, cmd.about));
68    for a in &cmd.args {
69        out.push_str(&format!(".RS\n.B <{}>\n{}\n.RE\n", a.name, a.help));
70    }
71    for f in &cmd.flags {
72        out.push_str(&format!(".RS\n.B {}\n{}\n.RE\n", f.invocation(), f.help));
73    }
74    if cmd.is_group() {
75        let mut new_parents = parents.to_vec();
76        new_parents.push(&cmd.name);
77        for sub in &cmd.subcommands {
78            man_command(out, app, sub, &new_parents);
79        }
80    }
81}
82
83fn markdown(app: &str, version: &str, about: &str, commands: &[Command]) -> String {
84    let mut out = String::new();
85    out.push_str(&format!("# {} {}\n\n{}\n\n", app, version, about));
86    out.push_str("## Commands\n\n");
87    for c in commands {
88        md_command(&mut out, app, c, &[]);
89    }
90    out
91}
92
93fn md_command(out: &mut String, app: &str, cmd: &Command, parents: &[&str]) {
94    let path = {
95        let mut p = parents.to_vec();
96        p.push(&cmd.name);
97        p.join(" ")
98    };
99    out.push_str(&format!("### `{} {}`\n\n{}\n\n", app, path, cmd.about));
100    if !cmd.long_about.is_empty() {
101        out.push_str(&format!("{}\n\n", cmd.long_about));
102    }
103    if !cmd.args.is_empty() {
104        out.push_str("**Arguments:**\n\n");
105        for a in &cmd.args {
106            let req = if a.required { "" } else { " _(optional)_" };
107            out.push_str(&format!("- `<{}>`{} — {}\n", a.name, req, a.help));
108        }
109        out.push('\n');
110    }
111    if !cmd.flags.is_empty() {
112        out.push_str("**Options:**\n\n");
113        for f in &cmd.flags {
114            out.push_str(&format!("- `{}` — {}\n", f.invocation().trim(), f.help));
115        }
116        out.push('\n');
117    }
118    if !cmd.examples.is_empty() {
119        out.push_str("**Examples:**\n\n```\n");
120        for ex in &cmd.examples {
121            out.push_str(&format!("{}\n", ex));
122        }
123        out.push_str("```\n\n");
124    }
125    if cmd.is_group() {
126        let mut new_parents = parents.to_vec();
127        new_parents.push(&cmd.name);
128        for sub in &cmd.subcommands {
129            md_command(out, app, sub, &new_parents);
130        }
131    }
132}