Conseils pratiques pour documentation (Sphinx) de projets (Python).

Lightning-talk pour DjangoCon-Toulouse 2012, par Benoît Bryon.

Présentation disponible sur http://tech.novapost.fr

• visibilité VS projet perso
• maturité VS méfiance
• pérennité VS fragilité du projet
• utile pour une équipe VS inutile pour les héros

Outils, conventions et bonnes pratiques :

• pour le code : nombre + notoriété
• pour la documentation : pas grand chose ?

=> collecte d'expériences (succès et échecs)

=> vision commune sur la documentation

=> outils concrets

• Générer du contenu : docstrings, manpages...
• Chasser l'obsolescence :
  • doc externe => liens
  • procédures d'installation => scripts
  • architecture => configuration

• Exemples, documentation narrative
  => doctests !
• Informations sur le projet (/about/)
  => .. include:: README, AUTHORS, LICENSE
• Guide du contributeur, conventions
  => feedback over convention !

• Canaliser les flux d'information
• Feedback-driven
• Support-driven

=> D'autres astuces sur http://docness.readthedocs.org

• docness
• documentation-style-guide pour Sphinx + rst2rst
• Templates de doc Sphinx
• Feature request : sphinx-apidoc + templates (voir aussi sphinx-autogen)
• Feature request : Sphinx + argparse|optparse => manpages