Haga Sphinx generar documentación de la clase RST de pydoc

Question

Actualmente estoy migrando toda la documentación existente (incompleta) a Sphinx .

El problema es que los usos de documentación Python docstrings (el módulo está escrito en C, pero es probable que no importa) y la documentación de la clase debe ser convertido en una forma utilizable para la Esfinge.

Hay sphinx.ext.autodoc , pero pone automáticamente a la docstrings actuales documento. Quiero generar un archivo de origen en ( RST ) basado en cadenas de documentación actuales, que luego editarla y mejorar de forma manual.

¿Cómo transformar las cadenas de documentación en RST para Sphinx?

Answer 1

El autodoc sí genera RST solamente no hay manera oficial para sacarlo de ella. El truco más fácil de llegar fue cambiando método sphinx.ext.autodoc.Documenter.add_line a mí emitir la línea se pone.

Como todo lo que quiero es una migración en tiempo, la salida estándar es lo suficientemente bueno para mí:

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)

impresiones AutoDoc genera ahora RST en stdout mientras se ejecuta y se puede simplemente redirigir o copiarlo en otro lugar.

Answer 2

mono parches autodoc por lo que funciona sin necesidad de editar cualquier cosa:

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

Por lo que sabemos que no hay herramientas para hacer esto automatizado. Por tanto, mi enfoque sería escribir un pequeño script que lee módulos relevantes (basados ??en sphinc.ext.autodoc) y lanza cadenas de documentación en un archivo (con formato apropiado).