Fare Sfinge generare la documentazione di classe RST da pydoc

Question

Al momento sto migrando tutti (incompleta) documentazione esistente a Sfinge .

Il problema è che gli usi di documentazione Python docstring (il modulo è scritto in C, ma probabilmente non importa) e la documentazione di classe deve essere convertito in una forma utilizzabile per la Sfinge.

sphinx.ext.autodoc , ma mette automaticamente docstring attuali al documento. Voglio generare un file sorgente in ( RST ) sulla base di docstrings attuali, che ho potuto poi modificare e migliorare manualmente.

Come si trasformerà in docstrings RST per Sphinx?

Answer 1

L'autodoc non genera RST solo non v'è alcun modo ufficiale per farlo fuori di esso. L'hack più semplice per ottenere che fosse cambiando metodo sphinx.ext.autodoc.Documenter.add_line per emettere me la linea si arriva.

Come tutto quello che voglio è una migrazione di tempo, allo standard output è abbastanza buono per me:

def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    print self.indent + line
    self.directive.result.append(self.indent + line, source, *lineno)

stampe AutoDoc ora generati RST su stdout durante l'esecuzione e si può semplicemente reindirizzare o copiare altrove.

Answer 2

scimmia patching autodoc in modo che funziona senza bisogno di modificare nulla:

import sphinx.ext.autodoc
rst = []
def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    rst.append(line)
    self.directive.result.append(self.indent + line, source, *lineno)
sphinx.ext.autodoc.Documenter.add_line = add_line
try:
    sphinx.main(['sphinx-build', '-b', 'html', '-d', '_build/doctrees', '.', '_build/html'])
except SystemExit:
    with file('doc.rst', 'w') as f:
        for line in rst:
            print >>f, line

Answer 3

Per quanto ne so non ci sono strumenti per farlo automatizzato. Il mio approccio sarebbe quindi di scrivere un piccolo script che legge moduli pertinenti (sulla base di sphinc.ext.autodoc) e getta le stringhe in un file doc (formattato in modo appropriato).