Sphinx+reStructuredText：条件文本的使用

在制作复杂的技术文档过程中，经常会碰到同一内容在不同的发布场景、不同用户角色、不同产品配置的情况下存在差异的情况，此时，借助reStructuredText
的 only指令和Sphinx指定 tag 输出的功能，可以在 sphinx-build 自动发布文档的过程中，只发布特定版本的文档。
本文主要分享笔者使用 Sphinx + reStructuredText 制作技术文档过程中，条件文本的使用经验。

reST only + tag = 指定内容发布 (tagged content)

only 指令是reStructuredText指令（Directive）之一，即指令生效范围内的内容仅在指定的逻辑表达式为真时才会包含在最后的文档中。

only 指令的语法如下：

.. only:: 

在上述逻辑表达式中，必须包含已定义好的标签（tag），表达式支持 布尔运算，并且支持 括号 的使用，以定义更为复杂的发布条件。例如：逻辑表达式可以为：html 或者 tag_A and (tag_B or tag_C)

only 指令只能用于控制文档的内容，对于标题级、文档内的ID定义（reST文档中称为 label）无效。

其中，对于标签 （ tag）的使用，需注意以下几点：

• Sphinx-build 默认的发布引擎对应的文件格式和名称可作为预定义的标签，无需额外定义，可直接使用。包括 html， latex， epub 等。

• 如需自定义标签 (tag)，可以在 conf.py 文件中自行添加。

• 自定义 tag 时，写法需满足 Python 标识符的写法，即 tag 仅能由大小写字母、下划线（且第一个字符不能为下划线）和数字组成。
  详细可以参考https://docs.python.org/3/reference/lexical_analysis.html#identifiers

下面就来介绍具体的用法和操作。

Step 1: 在 conf.py 文件中自定义 tag

除 sphinx-build 默认预定义tag外，用于 only 指令表达式中的 tag 必须先定义才能使用。

1. 在Sphinx的发布环境文件夹中（默认为 source 文件夹）找到 conf.py 文件。
2. 在文件中添加以下代码：

tags.has('tag_product_X')

建议统一以 “tag_” 开头设置，这样便于后期在文档中全局搜索标签。

conf.py 文件中定义 tag.png

Step 2: 在文档中使用 only 指定内容发布条件

在 reStructuredText 文件中，对于存在差异的内容，使用 only 指令，指定其发布条件。

.. only:: tag_product_X

   The following content will only be shown in the documents for product X.

Step 3: 指定 tag 发布

使用 sphinx-build 命令发布文档：

sphinx-build [options]   [filenames …] -t tag_product_X

以默认环境下发布PDF为例，发布product X的文档：

sphinx-build -M latexpdf source build -t tag_product_X

此外，也可以自行修改Makefile文件，将 -t 添加至 sphinx-build 命令中，仍然使用 make 命令即可以运行条件发布。