在制作復(fù)雜的技術(shù)文檔過程中腾仅，經(jīng)常會碰到同一內(nèi)容在不同的發(fā)布場景乒裆、不同用戶角色、不同產(chǎn)品配置的情況下存在差異的情況推励，此時(shí)鹤耍，借助reStructuredText
的only指令和Sphinx指定tag輸出的功能，可以在sphinx-build自動發(fā)布文檔的過程中验辞，只發(fā)布特定版本的文檔稿黄。
本文主要分享筆者使用 Sphinx + reStructuredText 制作技術(shù)文檔過程中，條件文本的使用經(jīng)驗(yàn)跌造。
reST only + tag = 指定內(nèi)容發(fā)布 (tagged content)
only 指令是reStructuredText指令（Directive）之一杆怕，即指令生效范圍內(nèi)的內(nèi)容僅在指定的邏輯表達(dá)式為真時(shí)才會包含在最后的文檔中。
only 指令的語法如下：
.. only:: <expression>
在上述邏輯表達(dá)式中，必須包含已定義好的標(biāo)簽（tag）陵珍，表達(dá)式支持 布爾運(yùn)算寝杖，并且支持 括號 的使用，以定義更為復(fù)雜的發(fā)布條件撑教。例如：邏輯表達(dá)式可以為：html 或者 tag_A and (tag_B or tag_C)
only指令只能用于控制文檔的內(nèi)容朝墩，對于標(biāo)題級、文檔內(nèi)的ID定義（reST文檔中稱為label）無效伟姐。
其中收苏，對于標(biāo)簽 （ tag）的使用，需注意以下幾點(diǎn)：
Sphinx-build 默認(rèn)的發(fā)布引擎對應(yīng)的文件格式和名稱可作為預(yù)定義的標(biāo)簽愤兵，無需額外定義鹿霸，可直接使用。包括
html秆乳，latex懦鼠，epub等。如需自定義標(biāo)簽 (tag)屹堰，可以在
conf.py文件中自行添加肛冶。自定義
tag時(shí)，寫法需滿足 Python 標(biāo)識符的寫法扯键，即tag僅能由大小寫字母睦袖、下劃線（且第一個(gè)字符不能為下劃線）和數(shù)字組成。
詳細(xì)可以參考https://docs.python.org/3/reference/lexical_analysis.html#identifiers
下面就來介紹具體的用法和操作荣刑。
Step 1: 在 conf.py 文件中自定義 tag
除 sphinx-build 默認(rèn)預(yù)定義tag外馅笙，用于 only 指令表達(dá)式中的 tag 必須先定義才能使用。
- 在Sphinx的發(fā)布環(huán)境文件夾中（默認(rèn)為
source文件夾）找到conf.py文件厉亏。 - 在文件中添加以下代碼：
tags.has('tag_product_X')
建議統(tǒng)一以 “tag_” 開頭設(shè)置董习，這樣便于后期在文檔中全局搜索標(biāo)簽。
Step 2: 在文檔中使用 only 指定內(nèi)容發(fā)布條件
在 reStructuredText 文件中爱只，對于存在差異的內(nèi)容皿淋，使用 only 指令，指定其發(fā)布條件恬试。
.. only:: tag_product_X
The following content will only be shown in the documents for product X.
Step 3: 指定 tag 發(fā)布
使用 sphinx-build 命令發(fā)布文檔：
sphinx-build [options] <sourcedir> <outputdir> [filenames …] -t tag_product_X
以默認(rèn)環(huán)境下發(fā)布PDF為例沥匈，發(fā)布product X的文檔：
sphinx-build -M latexpdf source build -t tag_product_X
此外，也可以自行修改Makefile文件忘渔，將 -t 添加至 sphinx-build 命令中高帖，仍然使用 make 命令即可以運(yùn)行條件發(fā)布。
