為你的 CLI 應用程式呈現文件

CLI 的說明文件通常包含命令中的 --help 說明和手冊 (man) 頁面。

透過 clap 和 clap_mangen crate，當你使用時就可以自動產生這些說明。

#[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 開啟它，就可以欣賞你的免費說明文件了。