如何使用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", 
      ...} 

我想知道的，是如果在獅身人面像中有一種方法在make html週期內加載yaml文件，請將某些reStructuredText格式（例如definition list）中的python字典轉換幷包含在我的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: 

，並在內部轉換爲：被轉換爲HTML之前

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 

。

Answer 1

最後，我找到了一種方法來實現我想要的。下面是如何做：

1. 創建一個python腳本（姑且稱之爲generate-includes.py），將產生reStructuredText的並將其保存在myrst.inc文件。 （在我的例子中，這將是腳本加載和解析YAML，但這是無關緊要的）。 確保此文件可執行！

2. 要插入您的動態生成的文檔使用include指令你的文檔你的主要.rst文件中，在點：

   .. include:: myrst.inc 
   

3. 修改Makefile的獅身人面像以便在生成時生成所需的.inc文件：

   myrst.inc: 
       ./generate-includes.py 
   
   html: myrst.inc 
       ...(other stuff here) 
   

4. 正常建立您的文檔與make html。

Answer 2

獅身人面像沒有內置任何東西來做你喜歡的事情。您可以創建自定義指令來處理文件，也可以在單獨的步驟中生成reStructuredText，並使用include指令包含生成的reStructuredText文件。

Answer 3

斯芬克斯確實支持定製擴展，這可能是最好的方法來做到這一點http://sphinx.pocoo.org/ext/tutorial.html。

Answer 4

我需要同樣的事情，所以我扔在一起，新的指令，似乎工作（我一無所知定製獅身人面像的指令，但到目前爲止，它的工作）：

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 5

的改進基於邁克爾的代碼，並內置包括指令：

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.

Answer 6

我知道這個問題很舊，但也許別人會發現它也很有用。

這聽起來像你並不需要執行任何python代碼，但你只需要重新格式化文件的內容。在這種情況下，你可能想看看獅身人面像 - 神仙（https://pypi.python.org/pypi/sphinx-jinja）。

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

jinja_contexts = yaml.load(yourFileHere) 

然後你可以使用神社模板寫出來的內容，並讓他們處理成REST輸入。