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

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

所以我的想法如下：

• 挂钩 Sphinx 运行并在 Sphinx 之前执行一些 Python 代码
• Python 代码从每个源文件中提取文本块（最顶层的多行注释块），并为每个源文件组装一个 reST 文件，其中包含该注释块和一些其他 reST 标记。
• 所有源文件都列在一个index.rst，生成适当的.. toctree::指示。
• 文本提取和转换是按源代码目录递归完成的。

所以主要问题是：如何挂接 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 and make.bat，因为真正的构建过程在 ReadTheDocs.org 上运行。 RTD 仅执行conf.py.

正如我之前的评论和 mertyildiran 的回答中所指出的，连接 Sphinx 语言的官方方法是创建一个扩展 http://www.sphinx-doc.org/en/stable/extdev/index.html#dev-extensions为 VHDL 实现一个新域。

许多其他语言已经这样做了 - 例如Erlang、PHP、CoffeeScript - 和 API - 例如HTTP REST - 仅举几例sphinx-contrib https://bitbucket.org/birkenfeld/sphinx-contrib。然而，这将花费很多时间，而你没有时间......因此，你可以选择自己进行一些快速解析，然后以某种方式将其挂接到你的 Sphinx 构建中。

由于您绕过了官方挂钩，因此这个问题变成了“如何在 Sphinx 构建中运行我自己的代码？”为此，我建议您只需遵循本地扩展的指南 - 即，将其放在单独的目录中，将其添加到您的路径中，然后导入并调用它。如中所述docs http://www.sphinx-doc.org/en/stable/config.html:

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

最后，这打开了使用 pyVhdl2Sch 之类的第三方包（再次同意 mertyildiran 的答案）来创建一些原理图的选项，然后也许可以编写静态rst围绕它的文件来解释原理图。