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

Question

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

所以我的想法如下:

• 在Sphinx之前进入Sphinx运行并执行一些Python代码
• Python代码从每个源文件(最顶层的多行注释块)中提取文本块,并为每个源文件组装一个reST文件,包括此注释块和一些其他reST标记.
• 所有源文件都列在a中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上运行.RTD仅执行conf.py.

Answer 1

正如我之前的评论和 mertyildiran 的回答中所指出的，连接 Sphinx 语言的官方方法是创建一个扩展来实现 VHDL 的新域。

\n\n

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

\n\n

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

\n\n

\n

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

\n

\n\n

最后，这提供了使用 pyVhdl2Sch 等第三方包（再次向 mertyildiran 的答案点头）来创建一些原理图的选项，然后可以在rst其周围编写静态文件来解释原理图。

\n