Comment utiliser Python pour générer par programmation une partie de la documentation Sphinx

Une amélioration basée sur le code de Michael et la directive intégrée:

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)

Celui-ci importe la sortie plus tôt afin qu'elle passe directement à travers l'analyseur. Il fonctionne également en Python 3.

J'avais besoin de la même chose, alors j'ai jeté une nouvelle directive qui semble fonctionner (Je ne sais rien des directives Sphinx personnalisées, mais cela a fonctionné jusqu'à présent):

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)

Il est utilisé comme suit:

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

Sphinx n'a rien intégré pour faire ce que vous aimez. Vous pouvez créer une directive personnalisée pour traiter vos fichiers ou générer le reStructuredText dans une étape distincte et inclure le fichier reStructuredText résultant à l'aide de la directive include.

Je sais que cette question est ancienne, mais peut-être que quelqu'un d'autre va le trouver utile.

Il semble que vous n'ayez pas besoin d'exécuter de code python, mais vous avez juste besoin de reformater le contenu de votre fichier. Dans ce cas, vous voudrez peut-être regarder sphinx-jinja (https://pypi.python.org/pypi/sphinx-jinja).

Vous pouvez charger votre fichier YAML dans le conf.py:

jinja_contexts = yaml.load(yourFileHere)

Ensuite, vous pouvez utiliser Jinja templating pour écrire le contenu et les traiter comme reST entrée.

Sphinx prend en charge les extensions personnalisées qui serait probablement la meilleure façon de le faire http://sphinx.pocoo.org/ext/tutorial.html.