clap-markdown

API 文档 | 变更日志 | 贡献

自动为 clap 命令行工具生成 Markdown 文档。

示例

为基本的 clap 应用生成 Markdown 文本

#[derive(clap::Parser)]
struct Cli {
    #[arg()]
    name: String,
}

let markdown: String = clap_markdown_dfir::help_markdown::<Cli>();

生成的 Markdown 示例

查看 clap 示例程序以及由 clap-markdown 生成的对应 Markdown

使用约定：CommandLineHelp.md

本节描述了使用 clap-markdown 生成 CommandLineHelp.md 文件的建议约定，该文件可以提交到源代码管理并作为在线文档查看。

1. 将隐藏的 --markdown-help 选项添加到您的 clap 应用程序中

use clap::Parser;
use clap_markdown_dfir::MarkdownOptions;

#[derive(Parser)]
struct Cli {
    #[arg(long, hide = true)]
    markdown_help: bool,
}

fn main() {
    let args = Cli::parse();

    // Invoked as: `$ my-app --markdown-help`
    if args.markdown_help {
        clap_markdown_dfir::print_help_markdown::<Cli>(MarkdownOptions::default());
    }
}

2. 调用 --markdown-help 生成 CommandLineHelp.md 文件

$ cargo run -- --markdown-help > docs/CommandLineHelp.md

3. 将 CommandLineHelp.md 保存到 git 中，并从项目的 README.md 或其他相关文档中链接到它。

对于具有多个相关可执行文件的项目，请考虑使用命令名作为后缀。例如：CommandLineHelp-your-app.md，CommandLineHelp-other-app.md。

将 CommandLineHelp.md 提交到版本控制可以轻松跟踪用户界面可见的变化。

使用 clap-markdown 的项目

以下项目使用 clap-markdown 生成 CommandLineHelp.md 参考文档

• wolfram-app-discovery — CommandLineHelp.md
• wolfram-cli — CommandLineHelp.md

如需请求将项目添加到此列表中，请提交一个 issue。

与 clap 的兼容性

当此 crate 支持 clap 的新 MAJOR 版本时，clap-markdown 的 MAJOR 版本号将更改。

兼容性历史

许可证

许可协议为以下之一

• Apache License, Version 2.0 (LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确表示，否则您提交的任何有意包含在作品中的贡献，如 Apache-2.0 许可证中定义，将按照上述方式双重许可，不附加任何额外条款或条件。

有关执行常见开发任务的说明，请参阅 Development.md。

有关维护此项目的说明，请参阅 Maintenance.md。