Machen Sphinx erzeugen RST Klasse Dokumentation von pydoc

Question

ich zur Zeit der Migration alle vorhandenen (unvollständige) Dokumentation zu Sphinx .

Das Problem ist, dass die Dokumentation verwendet Python Docstrings (das Modul in C geschrieben ist, aber es tut wahrscheinlich keine Rolle) und die Klassendokumentation muss in eine Form verwendbar für Sphinx umgewandelt werden.

Es gibt sphinx.ext.autodoc , aber es stellt automatisch aktuelle Docstrings auf die dokumentieren. Ich möchte auf dem gegenwärtigen Docstrings eine Quelldatei in ( RST ) erzeugen, das kann ich dann bearbeiten und verbessern manuell.

Wie würden Sie Docstrings in RST für Sphinx verwandeln?

Answer 1

Die Autodoc generiert RST nur es kein offizieller Weg ist es, um es aus. Der einfachste Hack, um es durch eine Änderung sphinx.ext.autodoc.Documenter.add_line Methode ist mir die Linie zu emittieren wird es.

Wie alles, was ich möchte eine Zeitmigration ist, auf stdout ausgegeben ist gut genug für mich:

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)

Jetzt Autodoc druckt RST auf stdout erzeugt beim Laufen und Sie können einfach umleiten oder kopieren Sie sie an anderer Stelle.

Answer 2

Affe Patchen Autodoc so funktioniert es ohne zu bearbeiten etwas brauchen:

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

Soweit ich weiß, gibt es keine automatisierten Tools, dies zu tun. Mein Ansatz wäre daher ein kleines Skript zu schreiben, die entsprechenden Module liest (basierend auf sphinc.ext.autodoc) und wirft doc-Strings in eine Datei (formatiert entsprechend).