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

Question

我已经为我的项目设置了一个 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 上运行。 RTD 只执行conf.py。

Answer 1

正如我之前的 cmets 和 mertyildiran 的回答中所指出的，连接到 Sphinx 以获取一种语言的官方方法是 create an extension 为 VHDL 实现一个新域。

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

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

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

最后，这打开了使用 pyVhdl2Sch 之类的第 3 方软件包的选项（再次对 mertyildiran 的回答表示赞同）创建一些示意图，然后可能在其周围写入您的静态 rst 文件来解释示意图。

Answer 2

你正试图用大锤敲碎坚果。

Sphinx 最初是为新的 Python 文档创建的，它具有 为 Python 项目的文档提供出色的工具，但是 C/C++ 也已经支持，计划添加特殊的 也支持其他语言。 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，熟悉项目结构。最终将 vhdl.py 添加到这个项目目录：https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains

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