模块化文档
mdoc的Python项目详细描述
MDOC
模块化文档
使用mdoc，您可以创建递归的模块化文档。它有四个主要功能：
- 在其他文档中包含整个文件。
- 在其他文档中包含文件片段。
- 在文档中使用外部定义的变量。
- 在文档中计算python表达式。
这是“模块化”部分。“递归”部分意味着包含的文档本身可以无限地包含其他文档。
例如，这个自述文件是从readme目录中的不同部分生成的。
MDOC标签
mdoc通过解析mdoc标记的输入文件来完成所有这些工作。这些标签看起来像：
{mdoc include file.ext}，包括文件file.ext{mdoc snippet eq1 from file.ext}，包括文件中名为eq1的片段file.ext{mdoc var1}，插入名为var1的变量{mdoc eval expression}，计算python表达式expression
您可能想知道，如果这个自述文件是使用mdoc生成的，那么我如何能够在不解析它的情况下键入{mdoc…}。这要归功于static选项，该选项防止解析包含的文件，并逐字包含这些文件：
{mdoc include file.ext static}包括file.ext，但不为mdoc标记解析它{mdoc include snippet eq1 from file.ext static}包含来自file.ext的片段eq1，但不为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
欢迎加入QQ群-->： 979659372
