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

时间:2011-08-30 22:46:33

标签: python documentation python-sphinx restructuredtext

我正在使用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文件,则以某些 reStructuredText 格式翻译python字典(例如definition list)并包含在我的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之前。

6 个答案:

答案 0 :(得分:21)

最后,我找到了实现我想要的方法。这是方法:

  1. 创建一个python脚本(让我们称之为generate-includes.py),它将生成 reStructuredText 并将其保存在myrst.inc文件中。 (在我的例子中,这将是加载和解析YAML的脚本,但这是无关紧要的)。 确保此文件可执行!!!
  2. 在文档的主要.rst文档中使用include指令,以便插入动态生成的文档:

    .. include:: myrst.inc
    
  3. 修改sphinx Makefile ,以便在构建时生成所需的.inc文件:

    myrst.inc:
        ./generate-includes.py
    
    html: myrst.inc
        ...(other stuff here)
    
  4. 使用make html正常构建文档

答案 1 :(得分:14)

基于迈克尔代码和内置include指令的改进:

import sys
from os.path import basename

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

from sphinx.util.compat 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.

答案 2 :(得分:8)

我需要同样的东西,所以我把一个似乎有效的新指令汇总在一起(我对自定义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"

答案 3 :(得分:4)

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

答案 4 :(得分:2)

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

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

您可以在conf.py

中加载YAML文件
jinja_contexts = yaml.load(yourFileHere)

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

答案 5 :(得分:0)

Sphinx支持自定义扩展,这可能是执行此操作的最佳方式http://sphinx.pocoo.org/ext/tutorial.html