sphinx 部分高级功能汇总说明

什么是sphinx 就不说了，在探索sphinx 中踩了一些坑，汇总出来供参考。原本是打算写一份类似于wiki的标准文档，看到了很多企业使用了sphinx来创建，然后在学习中产生了一些疑惑，并解决了，总结如下：

1，变量的使用，在conf.py 按照如下格式定义：

rst_epilog="""
.. |pnamex| replace:: wiki test project.  
.. |pnamex3| replace:: pnamex3 test project.  
.. |xxx| replace:: xxx for something.
"""

然后在正文中用|pnamex| 就可以直接实现变量替换，注意上面的rst_epilog是固定内容；没有查询过是否可以有其他，但是测试其他是不行的。

上面是全局的变量使用，如果只是文内使用，直接在文内定义，使用方法一样。

.. |pname| replace:: wiki test project.   

关于变量的使用，官方文档地址:

The build configuration file — Sphinx 1.3.1 documentation

2，条件式生产文档

有的时候不同版本的文档绝大部分内容一样，少部分不同，就可以使用

.. only:: tag 的方式区分，这样就可以分别创建各自匹配的文件，例如乐鑫在创建官方SDK的使用就使用了这样的方案。 用only 标签来区分esp8266 esp32 esp32 c3 ，如下：