如何让literalinclude精准引入指定C函数/结构体代码片段

原生literalinclude仅做纯文本层面的内容截取，没有内置语法解析能力，不存在相关原生配置可以实现你的需求，可通过以下两种可靠方案实现，两种方案均会在指定语法实体不存在时触发构建失败，保障引用准确性：

• 基于C语法解析扩展实现
  安装支持C语法树解析的Sphinx扩展后，直接用扩展提供的指令替换原生literalinclude即可。这类扩展底层依赖libclang对目标C源文件/头文件做完整语法分析，不会用行号、前缀文本这类不可靠的匹配规则。
  基础用法示例：

  .. c-literalinclude:: ./drivers/uart.c
     :extract: function:uart_init
     :extract: struct:uart_config
  

  上述指令会自动提取uart_init函数的完整实现、uart_config结构体的完整定义，自动处理跨行、条件编译等C语法场景；如果指定的函数、结构体在目标文件中不存在，会在构建阶段直接抛出明确错误终止流程，不会出现引用错内容、漏内容的问题。
  生效只需要把对应扩展加入conf.py的extensions配置列表即可，不需要调整其他文档配置。
• 自定义指令实现
  如果不想引入第三方扩展，可以自行实现轻量自定义指令，核心逻辑非常简单：
  1. 给指令传入目标文件路径、待提取的实体类型（函数/结构体/枚举/宏等）、实体名称三个参数
  2. 构建时调用libclang的Python绑定解析目标文件，生成完整抽象语法树
  3. 遍历语法树匹配对应类型和名称的节点，获取节点对应的起止行号
  4. 未匹配到对应节点直接抛出Sphinx构建级错误
  5. 匹配成功则读取对应行范围的源码内容，渲染为标准代码块输出
     该方案灵活度最高，可以按需定制提取规则，比如是否同步提取实体对应的Doxygen注释、是否跳过条件编译块内的无效定义等。

不要尝试用正则匹配自行实现提取逻辑，C语法存在跨行定义、宏展开、同名注释、条件编译等大量复杂场景，正则匹配的误判率极高，无法满足文档引用的准确性要求。

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