如何在 Sphinx 运行 时预处理源文件？
How to pre-process source files while a Sphinx run?
我已经为我的项目设置了一个 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 和 make.bat，因为真正的构建过程 运行 在 ReadTheDocs.org 上进行。 RTDs 只执行 conf.py.
您正在尝试使用大锤敲碎坚果。
Sphinx was originally created for the new Python documentation, and it has
excellent facilities for the documentation of Python projects, but
C/C++ is already supported as well, and it is planned to add special
support for other languages as well.
http://www.sphinx-doc.org/en/stable/
VHDL 目前不是 Sphinx 支持的语言，因为 VHDL 是一种硬件描述语言，它成为支持语言的优先级必须很低。你有两个选择，第一个也是我给你的建议：
1) 使用特定于 VHDL 的文档生成器工具而不是 Sphinx
VHDocL -
http://www.volkerschatz.com/hardware/vhdocl.html
用 Perl 编写的 VHDL 文档实用程序，基于 Doxygen。
pyVhdl2Sch - http://laurentcabaret.github.io/pyVhdl2Sch/
pyVhdl2Sch 是一个文档生成器工具。它以 VHDL 文件 (.vhd) 作为入口，并为每个输入文件生成一个 pdf/svg/ps/png 原理图。纯 Python 编写，对社区更友好，更及时。
Sigasi Studio XL 文档 - http://www.sigasi.com/products/
作为商业产品的 Sigasi Studio 高端版。
2) 为Sphinx项目做贡献并添加VHDL域
关注Sphinx Developer's Guide and become familiar with the project structure. Eventually add vhdl.py to this project directory: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains
第二个选项无法用 Whosebug 答案来解释。如果您想向 Sphinx 这样的开源项目添加更多功能，则由您决定。
如我之前的评论和 mertyildiran 的回答所述，挂接到 Sphinx 的一种语言的官方方法是 create an extension 为 VHDL 实现一个新域。
许多其他语言已经这样做了 - 例如Erlang、PHP、CoffeeScript - 和 API - 例如HTTP REST - 仅举几个来自 sphinx-contrib 的例子。但是，这将花费很多时间，而您没有……因此，您可以选择自己进行一些快速解析，然后以某种方式将其连接到您的 Sphinx 构建中。
由于您绕过了官方挂钩，这个问题变成了 "how do I run my own code inside a Sphinx build?" 为此，我建议您只需按照本地扩展的指南进行操作 - 即，将其放在一个单独的目录中，将其添加到您的路径，然后导入并调用它。如 docs 中所述：
The configuration file is executed as Python code at build time (using execfile(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
最后，这打开了使用像 pyVhdl2Sch 这样的第三方包的选项（再次点头同意 mertyildiran 的回答）来创建一些原理图，然后可能将你的静态 rst 文件写到它周围解释原理图。
我已经为我的项目设置了一个 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 和 make.bat，因为真正的构建过程 运行 在 ReadTheDocs.org 上进行。 RTDs 只执行 conf.py.
您正在尝试使用大锤敲碎坚果。
Sphinx was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well. http://www.sphinx-doc.org/en/stable/
VHDL 目前不是 Sphinx 支持的语言，因为 VHDL 是一种硬件描述语言，它成为支持语言的优先级必须很低。你有两个选择，第一个也是我给你的建议：
1) 使用特定于 VHDL 的文档生成器工具而不是 Sphinx
VHDocL - http://www.volkerschatz.com/hardware/vhdocl.html
用 Perl 编写的 VHDL 文档实用程序，基于 Doxygen。
pyVhdl2Sch - http://laurentcabaret.github.io/pyVhdl2Sch/
pyVhdl2Sch 是一个文档生成器工具。它以 VHDL 文件 (.vhd) 作为入口，并为每个输入文件生成一个 pdf/svg/ps/png 原理图。纯 Python 编写，对社区更友好，更及时。
Sigasi Studio XL 文档 - http://www.sigasi.com/products/
作为商业产品的 Sigasi Studio 高端版。
2) 为Sphinx项目做贡献并添加VHDL域
关注Sphinx Developer's Guide and become familiar with the project structure. Eventually add vhdl.py to this project directory: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains
第二个选项无法用 Whosebug 答案来解释。如果您想向 Sphinx 这样的开源项目添加更多功能，则由您决定。
如我之前的评论和 mertyildiran 的回答所述，挂接到 Sphinx 的一种语言的官方方法是 create an extension 为 VHDL 实现一个新域。
许多其他语言已经这样做了 - 例如Erlang、PHP、CoffeeScript - 和 API - 例如HTTP REST - 仅举几个来自 sphinx-contrib 的例子。但是，这将花费很多时间，而您没有……因此，您可以选择自己进行一些快速解析，然后以某种方式将其连接到您的 Sphinx 构建中。
由于您绕过了官方挂钩，这个问题变成了 "how do I run my own code inside a Sphinx build?" 为此，我建议您只需按照本地扩展的指南进行操作 - 即，将其放在一个单独的目录中，将其添加到您的路径，然后导入并调用它。如 docs 中所述：
The configuration file is executed as Python code at build time (using execfile(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
最后，这打开了使用像 pyVhdl2Sch 这样的第三方包的选项（再次点头同意 mertyildiran 的回答）来创建一些原理图，然后可能将你的静态 rst 文件写到它周围解释原理图。