是否可以将 Sphinx 自动模块扩展到 Python 以外的域？

Question

我希望使用 Sphinx 来记录 VHDL 源代码。理想情况下，我希望能够采用这样的 VHDL 类型：

type T_SDRAM_REQ is record
    req     : STD_LOGIC;
    wr      : STD_LOGIC;
    address : STD_LOGIC_VECTOR;
    wr_data : STD_LOGIC_VECTOR;
    wr_ben  : STD_LOGIC_VECTOR;
end record T_SDRAM_REQ;

并使用类似这样的 RST 指令：

.. vhdl:type:: sdram_pack.T_SDRAM_REQ is record
    :members:

从源代码中提取所有字段并为我进行 RST 化。

我已经创建了一个 Sphinx 域，但我突然意识到仅此是不够的 - 这实际上只是一堆自定义指令。我真正想要的是类似于 autoclass 或 automodule 的东西，它会扫描 Python 源文件以生成指令。

但据我所知，Sphinx 自动模块功能仅适用于 Python。是否可以扩展 Sphinx 以包含其他语言的类似功能？在 VHDL 中可能被称为 autopackage 或 autoentity，在 C++ 中我猜是 autonamespace 还是不同的 autoclass？我可以以某种方式将vhdl:autopackage:: 指令添加到我的域吗？从 Sphinx 源代码中我可以看出，我认为 automodule 指令不是 Python 域的一部分。

Answer 1

我自己的问题的答案是：是的。我设法做到了，但这并不容易，而且结果远非完美。

虽然 Sphinx 域 API 已经设置了一些通用基类和特定于 Python 的子类，但对于 autodoc 则不能这样说。一些 Python autodoc 类可以用作基类，但需要大量覆盖。

我的自动文档系统的组件是：

• 新指令VHDLAutoDirective，AutoDirective 的子类，它为文档和特殊属性维护单独的注册表，并从指令名称的开头修剪“vhdl:auto”，而不仅仅是“auto”。与原来一样，这调用了特定于对象的文档记录器。
• 新的记录器。一个通用 VHDL 文档器基类 VHDLDocumenter，然后是每个 VHDL 对象的子类。这些记录器完成所有繁重的工作，从指令中获取选项和内容，并解析 VHDL 以生成内容。这里的关键问题是 Python autodoc 依赖于它所记录的正在安装的模块。由于 Sphinx 是用 Python 编写的，因此很容易 import 那些已安装的模块并以这种方式提取所有必需的信息，例如 __doc__ 可用于提取文档字符串。对于任何其他语言，您必须首先找到包含要记录的对象的文件，然后对其进行解析。为了解决第一个问题，我添加了一个current-file 指令来为所有后续自动指令指定一个文件，并为我的文档器基类添加一个file 选项以允许按指令指定文件。这有点笨拙，因为文件的路径是相对于我的存储库的基础，并假设 Sphinx 在那里运行 - 如果 Sphinx 在子目录中运行，它将无法工作。第二次我编写了一个基本的分词器和解析器，之前我认为将原始源代码复制到 code-block 指令中可能会更好 - 现在我可以选择两者都做。
• 我的域中的一个add_autodocumenter 函数，它在域中注册一个指令，然后导入我的autodoc 模块并调用一个add_documenter 函数来注册documenter。然后，autodoc 模块的 setup 函数使用 auto 指令在每个对象记录器上调用 add_autodocumenter。这类似于 Python autodoc 所做的，但 Python 版本将其指令注册到应用程序而不是域。

还有很大的改进空间，但至少它可以证明这是可能的。