如何在Sphinx autodoc生成的文档中替换本地文件路径

有几种可行的方案可以自动替换生成文档中的本地路径，避免手动编辑的麻烦：

方案1：自定义autodoc文档字符串处理器 #

• 编写一个简单的Sphinx扩展，在autodoc解析函数文档时替换本地路径
• 创建扩展文件（比如path_replace_ext.py）：

import re

def setup(app):
    def process_docstring(app, what, name, obj, options, lines):
        # 匹配你的本地路径格式，这里以'/home/username/xxx'为例
        local_path_re = re.compile(r'/home/[\w-]+/(\w+/?)+')
        # 替换为通用占位符
        for idx, line in enumerate(lines):
            lines[idx] = local_path_re.sub(r'{PROJECT_ROOT}/\g<0>', line)
    
    # 绑定到autodoc的文档字符串处理事件
    app.connect('autodoc-process-docstring', process_docstring)

• 在项目的conf.py中添加这个扩展：

extensions = [
    'sphinx.ext.autodoc',
    # 其他已有扩展...
    'path_replace_ext'  # 引入自定义扩展
]

方案2：提前在函数文档中使用占位符 #

• 直接修改Python函数的默认参数和文档字符串，用通用占位符代替本地路径：

def process_config(config_path='{PROJECT_CONFIG_DIR}/settings.ini'):
    """处理配置文件
    
    参数:
        config_path: 配置文件路径，默认使用项目配置目录下的settings.ini
    """
    # 函数实现代码

• 这种方式不需要额外扩展，autodoc会直接读取占位符内容生成文档

方案3：在Sphinx构建后替换文档内容 #

• 通过Sphinx的doctree-resolved事件，在文档解析完成后批量替换路径：
• 在conf.py中添加以下代码：

import re

def replace_local_paths(app, doctree, docname):
    # 遍历文档树节点，替换所有匹配的本地路径
    path_pattern = re.compile(r'/Users/[\w-]+/project/(\w+)')
    for node in doctree.traverse():
        if hasattr(node, 'astext'):
            original_text = node.astext()
            modified_text = path_pattern.sub(r'{PROJECT_DIR}/\1', original_text)
            if modified_text != original_text:
                node[0] = modified_text

def setup(app):
    app.connect('doctree-resolved', replace_local_paths)

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