3.8.19. Leçon sur la génération de documentation via sphinx

3.8.19.1. Introduction

Sphinx est un générateur de documentation qui donne envie de documenter.

• Langage ascii -> subversion -> partage.
• Syntaxe rapidement comprise.
• Auto-documentations (python, voire fortran avec fortran_autodoc).
• Intégration d’exemples.
• Sorties propres en PDF et HTML (et +).
• Assistants pour la création.
• Personnalisation du rendu.
• Extensions.
• De plus en plus répandu.

Une syntaxe de base très claire :

Section
=======
Ref. : :func:`plot.map`

3.8.19.2. Exemple

Exemple des différentes étapes pour créer sa documentation :

1. Lancez l’assistant de création puis répondez aux questions.

   $ sphinx-quickstart
   

   Pour l’utilisation des extensions Sphinx : repondez y.

2. Éditez le fichier conf.py si vous le souhaitez.

3. Créez ou éditez vos fichiers de documentation. Par exemple :

   • index.rst : Fichier de base.
   • usersguide.rst : Manuel de l’utilisateur.
   • library.rst : Guide du développeur.

4. Générer la documentation

   Pour le html

   $ make html
   

   Pour le pdf

   $ make latexpdf
   

5. Visualisez les documentations dans le répertoire build.

Exemple pour le fichier index.rst :

.. doctree::

    usersguide
    library

Exemple pour le fichier library.rst :

Guide du developpeur
####################

:mod:`mymodule` --- Mon module
******************************

.. automodule:: mymodule