如何在Sphinx文档的.rst文件中展示version.h中的VERSION宏值？

这里有几种实用的方案，你可以根据项目的实际情况选择：

方法1：在conf.py中读取版本值，再在rst中引用 #

这是最直接的方案，不需要额外依赖扩展：

1. 在conf.py中添加版本解析逻辑
   打开Sphinx项目根目录下的conf.py，加入一段Python代码来读取并解析version.h：

   def get_app_version(version_file_path):
       with open(version_file_path, 'r') as f:
           for line in f:
               stripped_line = line.strip()
               if stripped_line.startswith('#define VERSION'):
                   # 拆分行内容提取版本号（你的版本没有引号，直接取第三个元素即可）
                   parts = stripped_line.split()
                   if len(parts) >= 3:
                       return parts[2]
       # 没找到版本时返回默认值，也可以根据需求抛出异常
       return "unknown"
   
   # 替换为你的version.h实际路径，比如项目根目录的话就写'../version.h'
   app_version = get_app_version('../path/to/version.h')
   
   # 把版本号赋值给Sphinx内置变量，这样可以用|version|直接引用
   version = app_version
   release = app_version
   
   # 也可以自定义一个替换标记，方便在rst里区分其他版本变量
   rst_epilog = f'.. |APP_VERSION| replace:: {app_version}'
   

2. 在.rst文件中引用版本号
   现在有两种引用方式可选：

   • 使用Sphinx内置的|version|标记：

     本软件当前版本为 |version|
     

   • 使用自定义的|APP_VERSION|标记：

     欢迎使用版本为 |APP_VERSION| 的软件
     

方法2：用CMake生成版本片段（适合CMake构建的项目） #

如果你的项目用CMake管理，可以让CMake自动生成包含版本号的rst片段，再在文档中引入：

1. 添加CMake处理逻辑
   在项目的CMakeLists.txt中加入：

   # 读取version.h的内容
   file(READ ${PROJECT_SOURCE_DIR}/version.h VERSION_HEADER_CONTENTS)
   # 用正则匹配提取VERSION的值
   string(REGEX MATCH "#define VERSION ([0-9a-zA-Z.-]+)" _UNUSED_MATCH ${VERSION_HEADER_CONTENTS})
   set(APP_VERSION ${CMAKE_MATCH_1})
   
   # 配置rst模板，生成实际的版本片段文件
   configure_file(
       ${PROJECT_SOURCE_DIR}/docs/version.inc.rst.in
       ${PROJECT_BINARY_DIR}/docs/version.inc.rst
       @ONLY
   )
   

2. 创建rst模板文件
   在docs目录下新建version.inc.rst.in，内容仅需：

   @APP_VERSION@
   

3. 在主rst文件中引入
   在需要显示版本的.rst文件里添加：

   本软件版本： .. include:: ../build/docs/version.inc.rst
   

   注意路径要对应CMake生成的文件实际位置。

方法3：自定义Sphinx指令（进阶灵活方案） #

如果需要更灵活的控制（比如在多个位置动态读取版本），可以写一个简单的Sphinx扩展：

1. 编写扩展代码
   在项目中新建sphinx_extensions/version_directive.py文件：

   from docutils import nodes
   from docutils.parsers.rst import Directive
   
   class ShowVersionDirective(Directive):
       required_arguments = 1  # 接收version.h的路径参数
   
       def run(self):
           version_path = self.arguments[0]
           with open(version_path, 'r') as f:
               for line in f:
                   if line.strip().startswith('#define VERSION'):
                       version = line.strip().split()[2]
                       return [nodes.Text(version)]
           return [nodes.Text("unknown version")]
   
   def setup(app):
       app.add_directive('show-version', ShowVersionDirective)
       return {'version': '0.1', 'parallel_read_safe': True}
   

2. 在conf.py中启用扩展

   extensions = [
       # 保留你已有的其他扩展...
       'sphinx_extensions.version_directive'
   ]
   

3. 在rst中使用自定义指令

   当前软件版本： .. show-version:: ../path/to/version.h
   

这些方案都能帮你实现版本号的自动同步，避免手动修改文档和代码导致的不一致问题~

内容的提问来源于stack exchange，提问作者AmiguelS