Rust Bindocs

一个辅助编写Rust二进制程序文档的工具。

Rustdoc是一个非常出色的工具，但它主要适用于库。编写应用程序的文档可能是一个头疼的问题，因为你通常需要从代码中引用类型，但又不想包含所有内部信息或要求最终用户查看代码文档。另一种选择是手动编写一切，但与代码更改保持同步可能是一个头疼的问题，而且很容易出错。

此工具通过提供基本模板引擎来简化此过程，该引擎可以直接从您的源代码生成文档，针对最终用户优化，并直接嵌入到现有文档中。

完全支持现有的Rustdoc注释，并且包含的Markdown似乎已经集成到您的文档中。

⚠️ 工具目前处于初级阶段。仅支持Markdown输出，并可能存在错误。

安装

cargo安装bindocs

crate

用法

该crate包含一个命令行界面。将其指向crate的根目录，可选地指定文档输入/输出目录，您的文档将被渲染出来。

参数

project_path

类型：PathBuf

crate根目录的路径。默认为当前目录。

docs_path

类型：PathBuf?

文档模板的路径。可以是单个文件的文件名，也可以是多个文件的目录。默认为 <project_path>/docs。

output_path

类型：PathBuf?

输出渲染文档的路径。可以是单个文件的文件名，也可以是多个文件的目录。默认为 <project_path>/target/bindoc。

在您的输入Markdown中，使用 <% template_blocks %> 来标记类型应自动注入的位置。您可以注入您的crate拥有的任何结构体或枚举。

例如，如果您有一个包含 MyConfig 结构体的 config 模块

struct MyConfig {
    /// Enables foo mode.
    foo: bool,
    
    /// Specifies the `bar` value to use.
    /// 
    /// # Example
    /// 
    /// ```json
    /// { "bar" = "baz" }
    /// ```
    bar: String,
}

您可以将它注入到文档中，如下所示

# My docs page

Lorem ipsum dolar sit amet.

<%  config::AppConfig  %>

Ornare lectus sit amet est placerat in egestas.

这将产生类似以下输出

## MyConfig

### foo

> Type: `bool`

Enables foo mode.

### bar

> Type: `String`

Specifies the `bar` value to use.

#### Example

```json
{ "bar": "baz" }
```

✅ 如果类型在您的项目中具有唯一名称，则可以省略路径（即仅 AppConfig），bindocs仍然可以解析它。

配置注入

每个注入可以使用 Corn 在类型路径之后、闭合括号之前进行单独配置。

例如，要更改标题深度

<%  config::AppConfig { depth = 3 }  %>

注入替换选项

标题

类型：bool

是否包含元素标题。默认为true。

深度

类型：usize

当前标题深度，从 0 开始。标题将放置在当前深度之上。例如，如果下一个标题应该是 ## h2，请使用深度为 1。

贡献

欢迎贡献！

如果您发现任何问题，请提交错误报告。

如果您有功能请求，请首先提交问题以允许讨论。更多选项和渲染格式很可能会被接受。