how - Cómo usar Python para generar mediante programación parte de la documentación de Sphinx

sphinx python example

Question

Estoy usando Sphinx para generar la documentación de un proyecto mío.

En este proyecto, describo una lista de comandos disponibles en un archivo yaml que, una vez cargados, da como resultado un diccionario en la forma {command-name : command-description} por ejemplo:

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

Lo que me gustaría saber es si hay un método en sphinx para cargar el archivo yaml durante el ciclo de creación de make html , traducir el diccionario de python en algún formato de texto reStructured (por ejemplo, una lista de definiciones ) e incluirlo en mi salida de html.

Espero que mi archivo .rst vea como:

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

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

y convertirse internamente a:

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

Antes de ser traducido a HTML.

Answer 1

Al final encuentro la manera de lograr lo que quería. Aquí está el cómo hacerlo:

1. Cree una secuencia de comandos de Python (llamémosla generate-includes.py myrst.inc ) que generará el texto reStructured y la guardará en el archivo myrst.inc . (En mi ejemplo, este sería el script que carga y analiza el YAML, pero esto es irrelevante). Asegúrese de que este archivo es ejecutable!

2. Use la directiva de include en su documento principal .rst de su documentación, en el punto donde desea que se inserte la documentación generada dinámicamente:

   .. include:: myrst.inc

3. Modifique el archivo Makefile de la esfinge para generar los archivos .inc necesarios en el momento de la compilación:

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

4. Construye tu documentación normalmente con make html .

Answer 2

Necesitaba lo mismo, así que junté una nueva directiva que parece funcionar (no sé nada acerca de las directivas Sphinx personalizadas, pero hasta ahora ha funcionado):

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)

Se utiliza de la siguiente manera:

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

Answer 3

Sé que esta pregunta es antigua, pero tal vez alguien más también la encuentre útil.

Parece que realmente no necesitas ejecutar ningún código de Python, pero solo necesitas reformatear el contenido de tu archivo. En ese caso, es posible que desee ver sphinx-jinja ( https://pypi.python.org/pypi/sphinx-jinja ).

Puedes cargar tu archivo YAML en el conf.py :

jinja_contexts = yaml.load(yourFileHere)

Luego, puede usar la plantilla jinja para escribir los contenidos y tratarlos como entrada reST.

Answer 4

Sphinx admite extensiones personalizadas que probablemente sean la mejor forma de hacerlo http://sphinx.pocoo.org/ext/tutorial.html .

Answer 5

Sphinx no tiene nada incorporado para hacer lo que te gusta. Puede crear una directiva personalizada para procesar sus archivos o generar reStructuredText en un paso separado e incluir el archivo resultante reStructuredText utilizando la directiva include.

Answer 6

Una mejora basada en el código de Michael y la directiva de inclusión incorporada:

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)

Éste importa la salida anterior para que pase directamente a través del analizador. También funciona en Python 3.