Je suis actuellement en train de migrer toute la documentation existante (incomplète) sur Sphinx .
Le problème est que la documentation utilise python docstrings (le module est écrit en C, mais Cela n'a probablement pas d'importance) et la documentation de la classe doit être convertie en une forme utilisable pour Sphinx.
Il y a sphinx.ext.Autodoc , mais il met automatiquement des doctorats actuels à la document. Je veux générer un fichier source dans ( RST ) en fonction de la DOCString actuelle, que je pourrais alors modifier et améliorer manuellement.
Comment transformeriez-vous Docstrings en RST pour Sphinx?
3 Réponses :
Autant que je sache, il n'y a pas d'outils automatisés pour le faire. Mon approche serait donc d'écrire un petit script qui lit les modules pertinents (basé sur SPHINC.EXT.Autodoc) et jette des chaînes Doc dans un fichier (formaté de manière appropriée).
L'AUTODOC génère une première heure seulement il n'y a pas de moyen officiel de le sortir. Le hack le plus facile pour obtenir était en changeant Comme tout ce que je veux, c'est une migration unique, la sortie sur stdout est Assez bon pour moi: p> sphinx.ext.autodoc.documenter.autodoc.documenter.add_line code> Méthode pour émettre moi la ligne qu'elle obtient. 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)
Nice, je veux juste ajouter le répertoire de ce fichier ~ / .virtualenvs / docs / lib / python2.7 / packages de site / sphinx / ext / , si vous utilisez virtualenv. Nom du fichier est, bien sûr, autodoc.py
Pour les débutants comme moi, n'oubliez pas d'utiliser des parens à Python 3.x, la nouvelle ligne doit être Imprimer (Self.indent + Line)
Singe Patching Autodoc de sorte qu'il fonctionne sans avoir à 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