cornerlibstone 0.1.0

Lib Cornerstone — a zero-dependency foundation for building command-line tools in Rust: argument parsing, nested subcommands, themeable help in multiple presets, structured errors and exit codes, config loading, interactive prompts, shell-completion and man/markdown generation, logging, JSON output, and root/destructive-operation guards.
Documentation
//! Documentation generation. Produces a `man` page (roff) or a Markdown
//! reference straight from the declared commands — the same specs that drive
//! help and completion — so a tool's docs never drift from its actual interface.
//! Exposed through the built-in `docs <man|markdown>` path.

use crate::spec::Command;

/// Output format for generated docs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DocFormat {
    Man,
    Markdown,
}

impl DocFormat {
    pub fn parse(s: &str) -> Option<DocFormat> {
        match s.to_lowercase().as_str() {
            "man" | "roff" => Some(DocFormat::Man),
            "markdown" | "md" => Some(DocFormat::Markdown),
            _ => None,
        }
    }
    pub fn all() -> [&'static str; 2] {
        ["man", "markdown"]
    }
}

/// Generate documentation for the app.
pub fn generate(
    app: &str,
    version: &str,
    about: &str,
    commands: &[Command],
    fmt: DocFormat,
) -> String {
    match fmt {
        DocFormat::Man => man(app, version, about, commands),
        DocFormat::Markdown => markdown(app, version, about, commands),
    }
}

fn man(app: &str, version: &str, about: &str, commands: &[Command]) -> String {
    let mut out = String::new();
    out.push_str(&format!(
        ".TH {} 1 \"\" \"{} {}\" \"User Commands\"\n",
        app.to_uppercase(),
        app,
        version
    ));
    out.push_str(".SH NAME\n");
    out.push_str(&format!("{} \\- {}\n", app, about));
    out.push_str(".SH SYNOPSIS\n");
    out.push_str(&format!(".B {}\n[\\fICOMMAND\\fR] [\\fIOPTIONS\\fR]\n", app));
    out.push_str(".SH COMMANDS\n");
    for c in commands {
        man_command(&mut out, app, c, &[]);
    }
    out
}

fn man_command(out: &mut String, app: &str, cmd: &Command, parents: &[&str]) {
    let path = {
        let mut p = parents.to_vec();
        p.push(&cmd.name);
        p.join(" ")
    };
    out.push_str(&format!(".TP\n.B {} {}\n{}\n", app, path, cmd.about));
    for a in &cmd.args {
        out.push_str(&format!(".RS\n.B <{}>\n{}\n.RE\n", a.name, a.help));
    }
    for f in &cmd.flags {
        out.push_str(&format!(".RS\n.B {}\n{}\n.RE\n", f.invocation(), f.help));
    }
    if cmd.is_group() {
        let mut new_parents = parents.to_vec();
        new_parents.push(&cmd.name);
        for sub in &cmd.subcommands {
            man_command(out, app, sub, &new_parents);
        }
    }
}

fn markdown(app: &str, version: &str, about: &str, commands: &[Command]) -> String {
    let mut out = String::new();
    out.push_str(&format!("# {} {}\n\n{}\n\n", app, version, about));
    out.push_str("## Commands\n\n");
    for c in commands {
        md_command(&mut out, app, c, &[]);
    }
    out
}

fn md_command(out: &mut String, app: &str, cmd: &Command, parents: &[&str]) {
    let path = {
        let mut p = parents.to_vec();
        p.push(&cmd.name);
        p.join(" ")
    };
    out.push_str(&format!("### `{} {}`\n\n{}\n\n", app, path, cmd.about));
    if !cmd.long_about.is_empty() {
        out.push_str(&format!("{}\n\n", cmd.long_about));
    }
    if !cmd.args.is_empty() {
        out.push_str("**Arguments:**\n\n");
        for a in &cmd.args {
            let req = if a.required { "" } else { " _(optional)_" };
            out.push_str(&format!("- `<{}>`{} — {}\n", a.name, req, a.help));
        }
        out.push('\n');
    }
    if !cmd.flags.is_empty() {
        out.push_str("**Options:**\n\n");
        for f in &cmd.flags {
            out.push_str(&format!("- `{}` — {}\n", f.invocation().trim(), f.help));
        }
        out.push('\n');
    }
    if !cmd.examples.is_empty() {
        out.push_str("**Examples:**\n\n```\n");
        for ex in &cmd.examples {
            out.push_str(&format!("{}\n", ex));
        }
        out.push_str("```\n\n");
    }
    if cmd.is_group() {
        let mut new_parents = parents.to_vec();
        new_parents.push(&cmd.name);
        for sub in &cmd.subcommands {
            md_command(out, app, sub, &new_parents);
        }
    }
}