在处理技术文档时，对于一些经常出现的内容可以将其定义为变量处理，便于多人协作时书写统一和自动更新。
本文介绍使用Sphinx+reStructuredText制作技术文档时，如何实现变量的功能。
关于变量
变量，顾名思义，即可以发生变化的值。在技术文档中，可以将一些经常出现或经常需要变化的文本处理为变量，以实现：
- 多人协同写作时保持形式统一
- 值变化时保证所有文档的自动更新
常见的变量文本有：
- 公司名称
- 产品名称
- 日期
- 版本
- 版权日期
使用过 Adobe FrameMaker 的用户知道，Adobe FrameMaker 支持变量的使用，并且包含系统变量和自定义变量两类。其中，
系统变量即 Adobe FrameMaker 默认提供的变量，例如文件名称、日期等，用户可以更改变量的值，但无法删除系统变量本身。
自定义变量即用户可以在 Adobe FrameMaker 创建的文档中自由定义并更改的变量，用户既可以更改变量的值，也可以增删变量本身。
与上述类似，Sphinx+reStructuredText 中也可以实现 “系统变量”和“自定义变量”的功能，“自定义变量中”又可以根据变量的生效范围，分为全局变量和局部变量。
下面就来看具体如何应用。
系统变量
在Sphinx配置环境中，系统默认提供了project、copyright、author、version、release等 “系统变量”（Sphinx系统中称之为“project information”），可以在使用 “sphinx-quickstart” 过程中输入，或者在后期生成的 conf.py 文件里个更改上述变量的值。
system_variable.png
Sphinx 安装完成后，提供
sphinx-quickstart工具自动得到 Sphinx 的初始环境和文件目录。详细步骤见 sphinx-quickstart
如何安装 Sphinx，详见官方文档 installing Sphinx
修改上述变量内容后，在后期自动发布生成的HTML和PDF中可以看见上述变量信息。
HTML
自定义变量
除 Sphinx 默认提供的 project information 相关变量外，用户也可以使用 reStructuredText 的替代语法（substitution）语法，随时自定义某些变量。
本文中介绍使用 reStructuredText 替代语法，实现自定义变量。
reStructuredText 替代语法（Substitutions）
reStructuredText 的替代语法，用定义的 |name| 来替代一小段文本或者标记语法。用法如下：
.. |name| replace:: replacement *text*
或者
.. |caution| image:: warning.png
:alt: Warning!
利用上述替代语法，就可以实现自定义变量的功能了。
如果希望该变量在所有的文档中生效，则可以在 conf.py 中使用增加以下命令行，传入替代语法，得到 “全局变量”。
例如，笔者的经验中，将产品名称、以及常用的特殊符号unicode编码等在 conf.py 定义，得到变量。之后，在任意项目文档中使用替代文本 |name| 的部分即可。
conf.py中定义“全局变量”
如果只是某个文档中，某一名词反复出现，则可以在当前 .rst 文档中，使用替代语法，得到 “局部变量”。
例如，某个文档中经常出现的某个参数名称，使用替代语法，可以保证书写一致，并便于后期自动修改更新。
替代语法得到“局部变量”
总结
以上就是在使用 Sphinx+reStructuredText 制作技术文档过程中，实现变量功能的经验。
后续介绍 Sphinx+reStructuredText 方案中条件文本 （conditional text）的使用。结合使用变量 （variable）和条件文本（conditional text）,不同需求下条件发布就可以实现了。
网友评论