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

Question

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

/src/main/resources

使用类似的RST指令：

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-ify。

我已经创建了一个Sphinx域名，但我觉得仅仅这一点还不够 - 这只是一堆自定义指令。我真正想要的是类似于autoclass或automodule，它扫描Python源文件以生成指令。

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

Answer 1

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

虽然Sphinx Domain API已经设置了一些通用基类和特定于Python的子类，但是autodoc也是如此。一些Python autodoc类可以用作基类，但需要大量的重写。

我的autodoc系统的组件是：

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

还有很大的改进空间，但至少它可以作为概念的证明，可以做到这一点。