SpacetimeDB/tools/ci/src/ci_docs.rs

use clap::{Command, CommandFactory};

use crate::Cli;

// TODO: use clap_markdown instead of this custom implementation in the future
pub fn generate_cli_docs() -> String {
    let mut cli = Cli::command();
    let usage = generate_markdown(&mut cli, 2);

    format!(
        "\
# SpacetimeDB's cargo ci

## Overview

This document provides an overview of the `cargo ci` command-line tool, and documentation for each of its subcommands and options.

{}
---

This document is auto-generated by running:

```bash
cargo ci self-docs
```",
        usage
    )
}

fn generate_markdown(cmd: &mut Command, heading_level: usize) -> String {
    let mut out = String::new();

    let heading = "#".repeat(heading_level);
    out.push_str(&format!("{} `{}`\n\n", heading, cmd.get_name()));

    if let Some(long_about) = cmd.get_long_about() {
        out.push_str(&format!("{}\n\n", long_about));
    }

    out.push_str(&format!("**Usage:**\n```bash\n{}\n```\n\n", cmd.render_usage()));

    let mut options = String::new();
    for arg in cmd.get_arguments() {
        let names = arg
            .get_long()
            .map(|l| format!("--{}", l))
            .or_else(|| arg.get_short().map(|s| format!("-{}", s)))
            .unwrap_or_else(|| arg.get_id().to_string());
        let help = arg
            .get_long_help()
            .or_else(|| arg.get_help())
            .map(|help| help.to_string())
            .unwrap_or_else(|| {
                eprintln!("Warning: argument `{}` is missing help text", arg.get_id());
                "".to_string()
            });
        options.push_str(&format!(
            "- `{}`: {}\n{}",
            names,
            help,
            if help.lines().count() > 1 { "\n" } else { "" }
        ));
    }

    if !options.is_empty() {
        out.push_str("**Options:**\n\n");
        out.push_str(&options);
        out.push('\n');
    }

    for sub in cmd.get_subcommands_mut() {
        out.push_str(&generate_markdown(sub, heading_level + 1));
    }

    out
}