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

Posted 2023-03-30

【中文标题】是否可以将 Sphinx 自动模块扩展到 Python 以外的域？

【英文标题】：Is it possible to extend Sphinx automodule to domains other than Python?

【发布时间】：2016-08-18 14:14:57

【问题描述】：

我希望使用 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 域的一部分。

【问题讨论】：

是的，内置的 autodoc 扩展仅适用于 Python。但是你所要求的应该是可能的。例如，对于 Java，有一个名为 javasphinx (github.com/bronto/javasphinx) 的扩展。我不明白为什么不能为 VHDL 实现类似的东西。

@mzjn 感谢您指出这一点，但是虽然它正在添加 Java 域和 apidoc 功能，但据我所知，它并没有添加 autodoc，这正是我所追求的。不能老实说我有 Java 设置来测试它。

相关：***.com/q/37420560/407651

【参考方案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 版本将其指令注册到应用程序而不是域。

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

【讨论】：

嗨，安迪，你的作品在 GitHub 或其他地方有链接吗？

@JosephGlover 恐怕不会。完成工作后不久我离开了公司，所以我不知道发生了什么事。