如何使用Python以编程方式生成Sphinx文档的一部分？

Question

我正在使用 Sphinx 为我的项目生成文档。

在此项目中，我在 yaml 文件中描述了可用命令的列表，该文件一旦加载，就会生成以下形式的字典{command-name : command-description} 例如：

commands = {"copy"  : "Copy the highlighted text in the clipboard",
            "paste" : "Paste the clipboard text to cursor location",
            ...}

我想知道的是，sphinx 中是否有一种方法可以在 make html< 期间加载 yaml 文件/code> 循环，翻译python字典一些reStructuredText格式（例如定义列表）并包含在我的 html 输出中。

我希望我的 .rst 文件看起来像：

Available commands
==================
The commands available in bla-bla-bla...

.. magic-directive-that-execute-python-code::
   :maybe python code or name of python file here:

在内部转换为： 。

Available commands
==================
The commands available in bla-bla-bla...

copy
  Copy the highlighted text in the clipboard

paste
  Paste the clipboard text to cursor location

并在翻译为 HTML 之前

Answer 1

最后我找到了一种方法来实现我想要的。操作方法如下：

1. 创建一个 python 脚本（我们称之为 generate-includes.py），该脚本将生成 reStructuredText 并将其保存在myrst.inc 文件。 （在我的示例中，这将是加载和解析 YAML 的脚本，但这无关紧要）。 确保此文件可执行！！！

2. 在文档的主 .rst 文档中使用 include 指令，如下所示：您希望将动态生成的文档插入到的位置：

   .. include:: myrst.inc
   

3. 修改 sphinx Makefile，以便在构建时生成所需的 .inc 文件：

   myrst.inc：
       ./生成-includes.py
   
   html: myrst.inc
       ...（这里还有其他东西）
   

4. 使用 正常构建文档make html。

Answer 2

基于 Michael 的代码和内置 include 指令的一项改进：

import sys
from os.path import basename

try:
    from StringIO import StringIO
except ImportError:
    from io import StringIO

from docutils.parsers.rst import Directive    
from docutils import nodes, statemachine

class ExecDirective(Directive):
    """Execute the specified python code and insert the output into the document"""
    has_content = True

    def run(self):
        oldStdout, sys.stdout = sys.stdout, StringIO()

        tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
        source = self.state_machine.input_lines.source(self.lineno - self.state_machine.input_offset - 1)

        try:
            exec('\n'.join(self.content))
            text = sys.stdout.getvalue()
            lines = statemachine.string2lines(text, tab_width, convert_whitespace=True)
            self.state_machine.insert_input(lines, source)
            return []
        except Exception:
            return [nodes.error(None, nodes.paragraph(text = "Unable to execute python code at %s:%d:" % (basename(source), self.lineno)), nodes.paragraph(text = str(sys.exc_info()[1])))]
        finally:
            sys.stdout = oldStdout

def setup(app):
    app.add_directive('exec', ExecDirective)

该指令较早导入输出，以便它直接通过解析器。它也适用于 Python 3。

Answer 3

我需要同样的东西，所以我组合了一个似乎有效的新指令（我对自定义 Sphinx 指令一无所知，但到目前为止它已经有效）：

import sys
from os.path import basename
from StringIO import StringIO

from sphinx.util.compat import Directive
from docutils import nodes

class ExecDirective(Directive):
    """Execute the specified python code and insert the output into the document"""
    has_content = True

    def run(self):
        oldStdout, sys.stdout = sys.stdout, StringIO()
        try:
            exec '\n'.join(self.content)
            return [nodes.paragraph(text = sys.stdout.getvalue())]
        except Exception, e:
            return [nodes.error(None, nodes.paragraph(text = "Unable to execute python code at %s:%d:" % (basename(self.src), self.srcline)), nodes.paragraph(text = str(e)))]
        finally:
            sys.stdout = oldStdout

def setup(app):
    app.add_directive('exec', ExecDirective)

它的使用方式如下：

.. exec::
   print "Python code!"
   print "This text will show up in the document"

Answer 4

Sphinx 没有任何内置功能可以做您喜欢的事情。您可以创建自定义指令来处理文件，也可以在单独的步骤中生成 reStructuredText，并使用 include 指令包含生成的 reStructuredText 文件。

Answer 5

我知道这个问题很老了，但也许其他人也会发现它很有用。

听起来你实际上不需要执行任何 python 代码，但你只需要重新格式化文件的内容。在这种情况下，您可能需要查看 sphinx-jinja (https://pypi.python.org/ pypi/sphinx-jinja）。

您可以在 conf.py 中加载 YAML 文件：

jinja_contexts = yaml.load(yourFileHere)

然后您可以使用 jinja 模板写出内容并将它们视为 reST 输入。

Answer 6

Sphinx 确实支持自定义扩展，这可能是实现此目的的最佳方式 http://sphinx.pocoo。 org/ext/tutorial.html。

Answer 7

不完全是您想要的答案，但也许是一个近似值：yaml2rst< /a>.它是从 YAML 到 RST 的转换器。不对 YAML 本身执行任何明确的操作，而是查找注释行（以 # 开头）并将它们拉出到 RST 块中（YAML 进入 code-block代码>s）。允许某种文字化的 YAML。

此外，语法突出显示的 YAML 非常可读（哎呀，这是 YAML，而不是 JSON！）。