为您的 CLI 应用程序渲染文档

CLI 的文档通常包括命令中的 --help 部分和手册（man）页面。

使用 clap 时，可以通过 clap_mangen 箱子自动生成这两个部分。

#[derive(Parser)]
pub struct Head {
    /// file to load
    pub file: PathBuf,
    /// how many lines to print
    #[arg(short = "n", default_value = "5")]
    pub count: usize,
}

其次，您需要使用 build.rs 在编译时从代码中应用程序的定义生成手册文件。

有一些需要注意的地方（例如您希望如何打包二进制文件），但现在我们只需将 man 文件放在 src 文件夹旁边。

use clap::CommandFactory;

#[path="src/cli.rs"]
mod cli;

fn main() -> std::io::Result<()> {
    let out_dir = std::path::PathBuf::from(std::env::var_os("OUT_DIR").ok_or_else(|| std::io::ErrorKind::NotFound)?);
    let cmd = cli::Head::command();

    let man = clap_mangen::Man::new(cmd);
    let mut buffer: Vec<u8> = Default::default();
    man.render(&mut buffer)?;

    std::fs::write(out_dir.join("head.1"), buffer)?;

    Ok(())
}

现在，当您编译应用程序时，项目目录中将会有一个 head.1 文件。

如果您在 man 中打开它，您将能够欣赏您的免费文档。