Sphinx 运行时如何预处理源文件? [英] How to pre-process source files while a Sphinx run?

问题描述

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

I have set up a Sphinx documentation for my project and would like to extract doc strings for the source files and embed them into the final documentation. Unfortunately, the source file's language (VHDL) is not supported by Sphinx. There seems to be no Sphinx domain for VHDL.

所以我的想法如下:

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

• Hook into the Sphinx run and execute some Python code before Sphinx
• The Python codes extracts text blocks from each source file (the top-most multi-line comment block) and assembles one reST file per source file, consisting of this comment block and some other reST markup.
• All source files are listed in an index.rst, to generate the apropriate .. toctree:: directive.
• The text extraction and transformation is done recursively per source code directory.

所以主要问题是:如何连接到 Spinx?

或者我应该在 conf.py 中导入并运行我自己的配置?

Or should I just import and run my own configuration in 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.

I can't modify the build process files: Makefile and make.bat, because the real build process runs on ReadTheDocs.org. RTDs only executes conf.py.

推荐答案

正如我在之前的评论和 mertyildiran 的回答中所指出的，将一种语言挂钩到 Sphinx 的官方方法是 创建扩展 以实现 VHDL 的新域.

As noted in my previous comments and mertyildiran's answer, the official way to hook into Sphinx for a language would be to create an extension to implement a new domain for VHDL.

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

This has already been done for many other languages - e.g. Erlang, PHP, CoffeeScript - and APIs - e.g. HTTP REST - just to name a few from sphinx-contrib. However, that is going to take a lot of time, which you don't have... You are therefore left with an option to do some quick parsing yourself and then hooking that into your Sphinx build somehow.

既然你绕过了官方的钩子，这个问题就变成了我如何在 Sphinx 构建中运行我自己的代码?"为此，我建议您只需遵循本地扩展的指南——即将它放在一个单独的目录中，将其添加到您的路径中，然后导入并调用它.如文档中所述:

Since you are bypassing the official hooks, this question becomes "how do I run my own code inside a Sphinx build?" For which, I would recommend that you simply follow the guidance for a local extension - i.e. put it in a separate directory, add that to your path, then import and invoke it. As noted in the docs:

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

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 等 3rd 方软件包的选项(再次点头 mertyildiran 的回答)来创建一些原理图，然后可能围绕它编写静态 rst 文件解释原理图.

As a final though, this opens up the options to use 3rd party packages like pyVhdl2Sch (with a nod again to mertyildiran's answer) to create some schematic and then maybe write your static rst files around it to explain the schematic.

这篇关于Sphinx 运行时如何预处理源文件?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！