如何使用sphinx扩展创建新文档

Question

从 sphinx 扩展程序中，如何在调用我的扩展程序的当前文档下创建新文档（新页面）。即，我有一个从第一个文件调用的扩展。

类似：

foo.rst
  .. myextension::

在myextension期间，我想在foo下生成新文件。比如：

foo/bar.html:
   * Some documentation in a new page
foo/baz.html:
   * More documentation in a new page

这是我的扩展的简化，如果有帮助的话：

class NetYnlInclude(Directive):
    def run(self):
        file = "my_file.txt"     
        self.state.document.settings.record_dependencies.add(file)                     
        parsed_str = parse(file) # Parses the file into a string
        self.state_machine.insert_input(
            statemachine.string2lines(parsed_str), filename)

        paragraph_node = nodes.paragraph()
        return paragraph_node

Answer 1

如果你想直接生成

.html

文件，我不知道如何将其与 Sphinx 集成。

如果您想生成

.rst

文件并且希望 Sphinx 处理您的新文档，您需要在 Sphinx 构建管道的早期阶段创建它们。

据我了解，像

build-inited

那样附加到 autosummary

 事件

就是这样做的方法。

所以你的扩展需要类似的东西

def setup(app: Sphinx) -> None:
    app.connect('builder-inited', generate)


def generate(app: Sphinx) -> None:
    # write .rst files here

现在请注意，任何地方都没有提及指令 -

generate

 无法访问任何已解析的 

.rst

 文档、指令等，因为此时尚未解析任何文档。如果您想从 

.rst

 文件中提取信息，您需要手动解析它们（这也是“自动摘要”的作用）。

或者，您的扩展可以接受一些配置选项来告诉它要摄取哪些文件以及生成什么。

有关更完整的答案，请参阅

这篇不错的博客文章和相应的带有代码的完整、独立的存储库。