Bons exemples de docstrings Python pour Sphinx

Question

Quelqu'un connaît-il de bons exemples de docstrings Python écrits avec Sphinx autodoc en tête ? Il serait utile de voir comment les docstrings sont formatés (espace, indentation, etc.) pour qu'autodoc donne une belle documentation.

Answer 1

Cette page contient la source d'un petit projet de démonstration qui utilise automodule et autoclass : http://packages.python.org/an_example_pypi_project/sphinx.html#full-code-example .

Les deux docstrings "googley" et "sphinxy" (ces derniers utilisent listes de champs d'information ) sont démontrés.

La sortie résultante est ici : http://packages.python.org/an_example_pypi_project/pkgcode.html .

Answer 2

Pour toute documentation de sphinx que vous trouvez sur le web, vous pouvez cliquer sur "Show Source" pour voir l'entrée ReST originale de cette page. Certaines pages de haut niveau sont générées automatiquement et n'ont pas cette possibilité, mais la plupart des pages de l'arbre de documentation auront la source ReST comme lien.

Le code source de python est probablement un bon point de départ pour un exemple : http://www.python.org/download/

Le site Sphinx répertorie d'autres projets utilisant Sphinx pour la documentation : http://sphinx.pocoo.org/examples.html

Lorsque j'ai commencé à utiliser Sphinx pour la documentation de python, j'ai trouvé ce site web vraiment pratique et utile :
http://matplotlib.sourceforge.net/sampledoc/

L'un des points clés de l'utilisation de Sphinx pour la documentation est que vous pouvez également mélanger des fichiers de documentation exclusifs dans vos répertoires de code source. Le fichier README de votre projet de premier niveau peut être au format ReST et peut être incorporé comme introduction ou page principale de la sortie de Sphinx. Si vous avez différents paquets ou groupes de fichiers source, vous pouvez écrire des introductions et des explications plus verbeuses pour aider les lecteurs à comprendre votre projet. Les chaînes de documents sont un excellent début, mais Sphinx vous donne également la possibilité de passer au niveau supérieur de manière transparente en créant progressivement une documentation plus complète ou plus détaillée sans avoir à passer à un nouveau format comme MS Word. Les chaînes de documents sont les détails -- classe par classe, méthode par méthode. Parfois, il est nécessaire de donner aux gens une vue d'ensemble du code et de leur indiquer les éléments cruciaux du code. *.rst les fichiers de documentation.

Si vous démarrez un nouveau projet, vous devriez commencer par rédiger au moins le manuel de l'utilisateur dans une *.rst qui cohabitera avec votre code avant même d'écrire une ligne de code (ce n'est peut-être pas "agile" ; je dirai mes "Ave Maria" pour cette transgression). Vous devez avoir une idée claire de ce que votre projet va faire et y réfléchir sous forme de texte avant de vous lancer dans le codage vous fera gagner du temps à long terme. Comme le "Zen du python" dit,

    If the implementation is hard to explain, it's a bad idea.
    If the implementation is easy to explain, it may be a good idea

De plus, lorsque le manuel de l'utilisateur et le guide du développeur (qui sont en grande partie orthogonaux !!) coexistent avec le code, il y a moins de difficultés à maintenir ces documents à jour.

Answer 3

J'ai utilisé ces deux projets à titre d'exemple, qui ont une très bonne documentation sur la consommation de Sphinx :

Céleri

http://celeryproject.org/

https://github.com/ask/celery

PyMongo

http://api.mongodb.org/python/

https://github.com/mongodb/mongo-python-driver/

Answer 4

Pour les projets de plus grande envergure, en particulier dans le domaine du calcul scientifique, la numpy/scipy Le guide de style docstring semble être une bonne source :

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard

Answer 5

La documentation officielle de Sphinx couvre également assez bien ce point (syntaxe de commentaire auto-doc) :

http://sphinx-doc.org/markup/desc.html

Voici une liste (incluant les réponses ci-dessus) de documentation spécialement conçue pour auto-doc :

http://raxcloud.blogspot.com/2013/02/documenting-python-code-using-sphinx.html http://matplotlib.org/sampledoc/cheatsheet.html http://pythonhosted.org/an_example_pypi_project/sphinx.html