如何在Sphinx+Breathe中自动生成可跳转的项目文件夹结构？

一、基于Doxygen XML输出的自定义脚本（最推荐，完全自动） #

既然你已经在用Breathe，而Breathe依赖Doxygen生成的XML输出，那我们可以直接利用Doxygen已经收集到的文件信息，写个简单的Python脚本自动生成带跳转链接的树形文件夹结构：

1. 脚本思路：

   • 遍历Doxygen输出的XML目录，提取所有源文件的路径
   • 将路径整理成嵌套的树形结构
   • 自动生成带跳转链接的RST格式列表，链接指向对应文件的literalinclude锚点

2. 示例脚本：

import os
from xml.etree import ElementTree as ET

def generate_file_tree(xml_dir):
    # 解析Doxygen的索引XML文件
    index_path = os.path.join(xml_dir, 'index.xml')
    tree = ET.parse(index_path)
    root = tree.getroot()
    
    # 提取所有源文件路径
    file_paths = []
    for compound in root.findall('.//compound[@kind="file"]'):
        file_path = compound.find('name').text
        file_paths.append(file_path)
    
    # 将路径转换为嵌套字典的树形结构
    tree_dict = {}
    for path in file_paths:
        parts = path.split('/')
        current_node = tree_dict
        # 遍历文件夹层级
        for folder in parts[:-1]:
            if folder not in current_node:
                current_node[folder] = {}
            current_node = current_node[folder]
        # 添加文件节点
        current_node[parts[-1]] = path
    
    # 将树形字典转换为RST格式的带链接列表
    def dict_to_rst(node, indent=0):
        rst_lines = []
        for name, value in sorted(node.items()):
            indent_str = '  ' * indent
            if isinstance(value, dict):
                # 文件夹节点
                rst_lines.append(f"{indent_str}- **{name}/**")
                rst_lines.extend(dict_to_rst(value, indent + 1))
            else:
                # 文件节点，链接到对应literalinclude的锚点
                anchor_name = name.replace('.', '-')  # 避免锚点含特殊字符
                rst_lines.append(f"{indent_str}- [{name}](#{anchor_name})")
        return rst_lines
    
    return '\n'.join(dict_to_rst(tree_dict))

if __name__ == '__main__':
    # 替换成你的Doxygen XML输出目录
    doxygen_xml_dir = '_build/doxygen/xml'
    rst_content = generate_file_tree(doxygen_xml_dir)
    # 将生成的内容写入RST文件
    with open('file_structure.rst', 'w') as f:
        f.write("# Project File Structure\n\n")
        f.write(rst_content)

3. 配套设置：
   确保你每个文件的literalinclude块都设置了锚点，比如：

   .. _my-source-cpp:
   .. literalinclude:: ../src/my_source.cpp
      :caption: my_source.cpp
      :linenos:
   

   这样脚本生成的[my_source.cpp](#my-source-cpp)就能直接跳转到对应的代码块。

二、结合Breathe-apidoc的半自动化方案 #

如果不想写脚本，也可以用breathe-apidoc工具自动生成单个源文件的RST文档，再通过Sphinx的toctree来组织树形结构：

• 运行breathe-apidoc为每个源文件生成独立的RST页面
• 在主文档中按文件夹层级嵌套使用toctree，把这些生成的RST文件分组
• 最终HTML会生成树形的导航菜单，点击就能跳转到对应文件的代码文档页面

这种方式的优点是不用自己写脚本，缺点是树形结构需要手动按文件夹分组配置toctree，适合文件结构不经常变动的项目。

三、半手动补全方案（适合小型项目） #

如果你的项目规模不大，可以先用系统的tree命令生成目录结构文本，再手动给每个文件名添加跳转链接：

tree src/ > structure.txt

然后把文本复制到RST文件中，给每个文件名加上[文件名](#锚点)的链接格式，这种方式最快，但每次文件结构变动都需要手动更新。

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