文档

模块化文档

使用 mdoc，您可以创建递归的模块化文档。它有四个主要特点：

1. 在其他文档中包含整个文件。
2. 在其他文档中包含文件片段。
3. 在整个文档中使用外部定义的变量。
4. 评估文档中的 Python 表达式。

这就是“模块化”部分。“递归”部分意味着包含的文档本身可以无限地包含其他文档。

例如，这个自述文件是从readme目录中的各个部分生成的。

mdoc 标签

mdoc 通过解析输入文件的 mdoc 标记来完成所有这些工作。这些标签看起来像：

1. {mdoc include file.ext}, 包括文件file.ext
2. {mdoc snippet eq1 from file.ext}eq1, 包括从文件中调用的片段file.ext
3. {mdoc var1}, 插入名为的变量var1
4. {mdoc eval expression}, 计算 Python 表达式expression

您可能想知道，如果这个自述文件是使用 mdoc 生成的，我如何能够在上面输入 {mdoc ...} 而不会对其进行解析。这要归功于该static选项，它可以防止解析包含的文件并逐字包含它们：

1. {mdoc include file.ext static}包含file.ext但不为 mdoc 标签解析它
2. {mdoc include snippet eq1 from file.ext static}包括eq1来自file.ext但不为 mdoc 标签解析它的片段

变量或评估没有静态选项，因为那没有任何意义。

片段定义如下：

# Inside file.ext
{mdoc snip snippet_name}
...
snippet contents
...
{mdoc unsnip snippet_name}

然后，您可以引用片段名称和它所在的文件以将其包含在另一个文档中：

# Inside main file
{mdoc snippet snippet_name from file.ext}

这对于包含可能随时间变化的代码片段以及其他波动的内容非常方便。

当然，单词include, snippet, snip,unsnip和eval是保留的，不能用作 mdoc 变量名。

用法

安装后使用 mdoc 很简单。只需导航到主文档模板所在的文件夹并运行：

mdoc --input INPUT_DOCUMENT --output OUTPUT_DOCUMENT --variables VARIABLES_JSON

这将解析INPUT_DOCUMENT、插入在 中定义的任何变量VARIABLES_JSON并吐出OUTPUT_DOCUMENT。

如果您不想生成输出文件而只是想看看输出的样子，您可以--output OUTPUT_DOCUMENT将--dryrun.

如果您忘记了整个文档所需的所有变量，您可以使用--showvariables而不是--output或--dryrun，它会输出您需要的所有变量的 JSON 格式列表。您可以将其通过管道传输到文件中，以使事情变得非常简单！

mdoc --input INPUT_DOCUMENT --showvariables > VARIABLES_JSON