如何通过API在Sphinx/docutils中创建新文档？

Question

我为 Sphinx 编写了一个新的扩展，作为一个为硬件描述语言 VHDL 提供多个指令、角色和索引的域。该扩展应能够自动记录语言结构。在 VHDL 中，我们有例如实体/架构或包/包体。这些可以成对记录在各个 docutils 文档中，因此每种语言构造在文档中都有一个单独的 URL（或 PDF 中的页面）。

我正在寻找在 Sphinx/docutils 中创建新文档的解决方案。根据 docutils API 的描述，文档是 doctree（文档树）的根元素。根据 Sphinx 文档，指令是文档树中被使用的项目，并且可以向周围的文档树发出新节点。所以这是一种翻译/替换方法。

没有任何文档能够提供创建新文档的方法。

看

autodoc

延伸部分，有2条边。 Sphinx 附带

sphinx.ext.autodoc

。它提供

.. auto***

指令来自动记录 Python 语言结构。它要求用户将数十到数百个自动指令放入重构文本中。因为它会自动记录例如类或模块，但对于一个庞大的项目来说，这是一项大量的工作。

此外，还有autoapi，它可以读取给定包或模块的Python代码，并在加载Sphinx时动态生成ReST文件。然后处理这些包含自动指令的文件。

据我了解，autoapi 通过编写 ReST 文件解决了创建 docutils 文档的问题，因此 Sphinx 使用文档树生成文档实例，然后 Sphinx 的 autodoc 跳入并用文档字符串中的内容替换它们。

所以，在我迄今为止所做的所有调查之后，我的问题是：

• 如何创建 docutils 或 Sphinx 文档来获取我想要自动记录的每个项目的 HTML 文件？
• 或者我是否总是需要像 Carlos Jenkins 的 autoapi 一样进行 hack，并创建 ReST 文件作为虚拟文件或使用自动指令，以便我可以使用 Sphinx/autodoc 从指令到文档节点的替换功能？

---

为什么我不喜欢 autoapi 方法？我已将 VHDL 文件解析为代码文档对象模型 (CodeDOM) 形式的输入。我不想将解析 VHDL 文件序列化为 ReST，再次解析它，再次构建源文件的模型，这样我就可以转换为文档节点，如部分、段落和列表。

我可以为 docutils 生成文档节点，但我需要多个文档，因此我可以将内容分发到数百个文档文件（HTML 文件）。

Answer 1

我处于类似的情况，我现在正在考虑为每个源文件生成一个 html 文件。以下是我发现您的问题时所在位置的快照：

您可以告诉 sphinx 在构建时解析其他文件类型。在conf.py中：

source_suffix = {
    '.rst': 'restructuredtext',
    '.something': 'my_language',  # Will call the my_language parser for .something files
}

然后创建您自己的扩展（可以是您创建的 VHDL 域的一部分）。无论是在

my_extension.py

或

my_extension/{__init__.py,etc}

from docutils import nodes

class MyLanguageParser(Parser):
    supported = ("my_language",)  # Declate supported languages
    def parse(self, inputstring, document):
        # Do something more complex, but a document can be created from the file (contents in inputstrings)
        txt = nodes.Text('HI')
        document += txt

def setup(app):  # This is called when loading the extension
    app.add_source_suffix('.something', 'my_language')
    app.add_source_parser(MyLanguageParser)

    return {'version': '0.1'}  # Optional, but nice to version your extension

现在，当调用

sphinx-build

时，例如使用

make html

，您的解析器将被调用并为每个输入文件生成一个输出页面。

---

要回答问题的标题，您还可以通过以下方式以编程方式构造新的任意文档：

from sphinx.util.docutils import new_document
from docutils.core import publish_doctree, publish_from_doctree
from docutils import nodes

# create a new document
doc = new_document('mydoc')
txt = nodes.Text('HI')
doc += txt

# Alternatively, you can also build it from rst:
rst = """
Doc Title
=========

some content
"""
doc = publish_doctree(rst)

with open('mydoc.html', 'wb') as f:
    f.write(publish_from_doctree(doc, writer_name='html'))

最后一部分摘自这里。