Faites Sphinx générer des documents de classe RST de pydoc

Question

Je migration actuellement toute la documentation existante (incomplète) Sphinx .

Le problème est que la documentation utilise Python docstrings (le module est écrit en C, mais il n'a probablement pas) et la documentation de la classe doit être convertie en une forme utilisable pour Sphinx.

Il est sphinx.ext.autodoc , mais il met automatiquement docstrings en cours à la document. Je veux générer un fichier source dans ( RST ) basée sur docstrings en cours, que je pourrais alors modifier et d'améliorer manuellement.

Comment voulez-vous transformer en docstrings RST pour Sphinx?

Answer 1

Le autodoc ne génère que RST il n'y a aucun moyen officiel pour le faire sortir. Le hack le plus facile de l'obtenir était en changeant de méthode sphinx.ext.autodoc.Documenter.add_line pour me émettre la ligne qu'il obtient.

Comme tout ce que je veux est une migration de temps, la sortie est à stdout assez bon pour moi:

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)

imprime autodoc générés TVD sur stdout pendant la course et vous pouvez simplement rediriger ou le copier ailleurs.

Answer 2

Correctif singe autodoc il fonctionne sans avoir besoin de modifier quoi que ce soit:

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

Pour autant que je sais qu'il existe des outils automatisés pas de le faire. Mon approche serait donc d'écrire un petit script qui lit les modules concernés (sur la base sphinc.ext.autodoc) et lance des chaînes de documentation dans un fichier (au format approprié).