Sphinx 中的源代码级转换

Question

我正在尝试编写执行源代码级转换的 sphinx 扩展，但我不知道如何实际更改输出文件。

我的扩展看起来像这样：

def my_source_handler(app, docname, source):
    import re
    print 'test'
    source = [re.sub("foo", "bar", source[0])]
    return source

def setup(app):
    app.connect('source-read', my_source_handler)
    app.add_config_value('my_source_handler_include', True, False)

但是，当我将模块添加到扩展列表并 build html 时，它会打印 'test' 但实际上不会将 "foo" 更改为 "bar"在输出 HTML 文件中。

Sphinx documentation 有点含糊，说 "You can process the contents and replace this item to implement source-level transformations" 关于源参数。

问题是我不确定应该如何替换源参数。

Answer 1

实际上，经过一番挖掘我发现，您应该替换 source 的第一个（也是唯一一个）元素的内容，而不是替换 source 本身，例如：

def my_source_handler(app, docname, source):
    import re
    print 'test'
    source[0] = re.sub("foo", "bar", source[0])

Sphinx 中的源代码级转换

Source-level transformation in Sphinx

python

python-sphinx