Python 如何在Sphinx运行时预处理源文件？

我已经为我的项目建立了一个Sphinx文档，希望提取源文件的文档字符串，并将它们嵌入最终文档中。不幸的是，Sphinx不支持源文件的语言（VHDL）。VHDL似乎没有Sphinx域

因此，我的想法如下：

• 钩住Sphinx运行并在Sphinx之前执行一些Python代码
• Python代码从每个源文件（最上面的多行注释块）中提取文本块，并在每个源文件中组合一个reST文件，由该注释块和一些其他reST标记组成
• 所有源文件都列在

  索引.rst

  中，以生成适当的

  。。目录树：：

  指令
• 文本提取和转换是按源代码目录递归完成的

所以主要的问题是：如何连接到Spinx？

或者我应该在

conf.py

中导入并运行自己的配置吗

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
from my_preprocessor import my_proc
proc = my_proc()
proc.run()
#
# Test documentation build configuration file, created by
# sphinx-quickstart on Tue May 24 11:28:20 2016.
# ....

---

我无法修改生成过程文件：

Makefile

和

make.bat

，因为真正的生成过程在ReadTheDocs.org上运行。RTDs仅执行

conf.py

您试图使用大锤敲开螺母

Sphinx最初是为新的Python文档创建的，它已经 用于Python项目文档的优秀工具，但是 C/C++也已经得到支持，并且计划添加特殊的 对其他语言的支持。

VHDL目前不是Sphinx支持的语言，因为VHDL是一种硬件描述语言，所以成为受支持语言的优先级必须较低。你有两个选择，第一个也是我给你的建议：

1）使用VHDL特定的文档生成器工具而不是Sphinx

VHDocL-

基于Doxygen，用Perl编写的VHDL文档实用程序

pyVhdl2Sch-

pyVhdl2Sch是一个文档生成器工具。它将VHDL文件（.vhd）作为条目，并为每个输入文件生成pdf/svg/ps/png原理图。用纯Python编写，更友好，更及时

Sigasi Studio XL文档-

Sigasi Studio的高端版，这是一种商业产品

2）参与Sphinx项目并添加VHDL域

遵循并熟悉项目结构。最终将vhdl.py添加到此项目目录：

---

第二个选项不能用StackOverflow答案解释。如果您想向Sphinx这样的开源项目添加更多功能，这取决于您

正如我之前的评论和mertyildiran的回答中所指出的，为一种语言连接到Sphinx的正式方式是为VHDL实现一个新的域

许多其他语言（如Erlang、PHP、CoffeeScript）和API（如HTTPREST）都已经实现了这一点，仅举几个例子。然而，这将需要很多时间，你没有。。。因此，您可以选择自己进行一些快速解析，然后以某种方式将其连接到Sphinx构建中

因为您绕过了官方的钩子，所以这个问题变成了“如何在Sphinx构建中运行我自己的代码？”对于这个问题，我建议您只需遵循本地扩展的指导，即将其放在单独的目录中，将其添加到您的路径中，然后导入并调用它。如报告所述：

配置文件在构建时作为Python代码执行（使用execfile（），并将当前目录设置为其包含目录），因此可以执行任意复杂的代码。然后，Sphinx从文件的命名空间中读取简单名称作为其配置

---

最后，这为使用第三方软件包如pyVhdl2Sch（再次同意mertyildiran的回答）创建一些原理图打开了选项，然后可能会在其周围编写静态

rst

文件来解释原理图。

有什么原因不能这样做吗？编写扩展非常复杂（解析器，对象模型适配器）用于我的目标语言…预处理可能更容易。上面提到的工具中没有一个与ReadTheDocs一起工作，因此我没有选择这些工具。也许更好的类比是使用键盘破解Paebel？：）作为更新：我的问题发布到这里已经过了一段时间。我在上发布了我的VHDL解析器的第一个示例。有没有办法从Sphinx Contrib人员那里获得社区支持来创建适配器？我认为最好的办法是查看。有一个邮件列表和iRC频道供初学者使用。。。