10

我已经为我的项目设置了一个 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.

4

2 回答 2

4

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

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

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

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

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

于 2016-09-21T14:16:14.740 回答
3

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

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 开发人员指南并熟悉项目结构。最终将vhdl.py添加到这个项目目录：https ://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains

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

于 2016-09-21T12:40:32.697 回答