Sphinx-doc

Créé en 2008 par Geord Brandl, Sphinx-doc visait alors à corriger un manque : la création de documentation pour Pythonhttps://docs.python.org/2/.

Il a été peu à peu adopté pour d'autres usages par la suite, dont entre autres la création de documentation de code source.

À ce titre, il a alors officiellement remplacé des outils tels qu'Epydoc.

L'une des particularités, et des forces, de Sphinx-doc, c'est la possibilité de choisir un template permettant à la fois de modifier l'organisation de la page, mais également l'apparence visuelle (couleur).

Sphinx-doc est livré avec plusieurs templates de base, dont le template par défaut qui est extrêmement personnalisable.

Mais outre ces templates, vous pouvez également en trouver de nombreux sur le net, généreusement proposés par des membres de la communauté, avec plus ou moins d'options.

Enfin, sachez que si vous désirez développer votre propre template pour des raisons marketing par exemple, la documentation officiellehttp://sphinx-doc.org/theming.html?highlight=template#creating-themes vous fournit tous les éléments nécessaires à sa création.

II-B-1. Les templates standards▲

II-B-2. Personnaliser le template de base : default▲

Nous allons ici nous attarder un peu sur le template « default ». Pourquoi ce thème ? Tout simplement parce qu'outre le fait d'être le thème par défaut, et donc être disponible de base, c'est également un des thèmes les plus personnalisables.

Voyons maintenant plus amplement comment le configurer :

Option	Type	Description
rightsidebar	true or false	Position de la barre de menu (à gauche (« false ») ou à droite).
stickysidebar	true or false	Barre de menu fixe (« false » ) ou non.
externalrefs	true or false	Afficher d'une couleur différente les liens internes et externes.
footerbgcolor	CSS color	Couleur de fond du pied de page.
footertextcolor	CSS color	Couleur du texte du pied de page.
sidebarbgcolor	CSS color	Couleur de fond de la barre de menu.
sidebartextcolor	CSS color	Couleur du texte de titre dans la barre de menu.
sidebarlinkcolor	CSS color	Couleur de texte liens vers les pages de la doc.
relbarbgcolor	CSS color	Couleur des barres haut et bas.
relbartextcolor	CSS color	Couleur du texte de titre.
relbarlinkcolor	CSS color	Couleur du texte lien.
bgcolor	CSS color	Fond de la page normal.
textcolor	CSS color	Couleur du texte de la page.
linkcolor	CSS color	Couleur du lien non visité.
visitedlinkcolor	CSS color	Couleur du lien visité.
headbgcolor	CSS color	Couleur de fond des titres.
headtextcolor	CSS color	Couleur du texte de titre.
headlinkcolor	CSS color	Couleur des liens de titre
codebgcolor	CSS color	Couleur de fond pour le code.
codetextcolor	CSS color	Couleur de texte pour le code.
bodyfont	CSS font-family	Police pour le texte.
headfont	CSS font-family	Police pour les titres.

Les logos ne peuvent excéder 200 pixels de large.

II-B-3. Quelques templates supplémentaires▲

Les formats de sorties proposés sont multiples. Voici les principaux (liste non exhaustive) :

Le dossier « _static » est le dossier par défaut contenant les images qui seront utilisées dans la documentation.

Pour une compatibilité optimale, je vous conseille le format PNG, qui permet entre autres la transparence.

Ce dossier est celui qui contiendra vos templates supplémentaires si besoin.

C'est le fichier d'index, votre page de démarrage en quelque sorte. L'extension rst correspond au fichier ReST.

Nous reviendrons sur son fonctionnement, une fois les bases du langage ReST passées en revue.

Le fichier conf.py est le fichier contenant toute la configuration du projet de documentation : nom du projet, version, auteur, où trouver les images, log, quelles sont les options activées…

L'ensemble des éléments pouvant être paramétrés sont listés ICIhttp://sphinx-doc.org/config.html?highlight=conf#module-conf. Nous allons passer en revue les principaux et plus utiles.

Dans le fichier conf.py, ils sont presque tous présents, mais commentés. Pour en activer et modifier un, il vous suffit donc de le décommenter.

III-D-1. Langue▲

language = 'fr'

III-D-2. Configuration HTML▲

ReST, pour Restructured Text est en réalité non pas un nouveau langage à part entière, mais une évolution de langages plus anciens.

SeText et Structured Text furent créés respectivement en 1992 et 1993. Ces langages permirent la naissance du ReST, qui vit le jour dans le but d'uniformiser la façon de coder et de corriger les défauts de ses prédécesseurs.

Son nom et surtout son acronyme visent à rappeler ses origines.

Utilisé depuis le début de XXI^e siècle par la communauté Python, il est depuis 2008 partie intégrante de la communauté, notamment avec son rattachement à Sphinx-doc.

ReST repose sur un principe très simple : appliquer les principes de la programmation à l'écriture de documentation.

En d'autres termes, imposer un certain formalisme afin de pouvoir générer n'importe quel type de documentation.

De plus, au fil du temps, certains mots-clés, des keywords, supplémentaires sont venus s'ajouter aux possibilités offertes par ReST, lui conférant la possibilité de s'interfacer avec certains langages de programmation par exemple.

Quelle que soit l'action que vous désirerez réaliser avec ReST, certaines règles seront toujours valables. Ce sont ces règles que nous allons voir dans cette partie.

IV-C-1. Les directives▲

.. <nom>:: <arguments>
   :<options: <valeur> 
   <ligne vide éventuelle, parfois obligatoire>
   <le texte associé>

IV-C-2. Le fichier index.rst▲

   <nom>

.. toctree:: 
   :maxdepth: 2 

   Page0 
   Page1

IV-C-3. Espaces et sauts de ligne▲

IV-D-1. Gras▲

**Exemple de texte en gras**

IV-D-2. Italique▲

*Exemple de texte en italique*

Exemple de texte avec un \ **mot**\  en gras

En ReST, les titres sont soulignés d'un caractère spécial indiquant leur niveau. Un même titre doit systématiquement être souligné du même caractère. Il doit y avoir autant de caractères spéciaux que de caractères dans le titre.

Vous pouvez considérer qu'il existe cinq niveaux principaux pour les titres. Cela permet de couvrir en général l'ensemble du besoin.

*************
Titre de page 
************* 

Titre de niveau 1 
***************** 

Titre de niveau 2 
================= 

Titre de niveau 3 
----------------- 

Titre de niveau 4 
~~~~~~~~~~~~~~~~~ 

Titre de niveau 5 
+++++++++++++++++

IV-H-1. Classique▲

Liste classique 

 * ligne 1 
 * ligne 2 
 * ligne 3

IV-H-2. Numérotée▲

Liste numérotée manuelle
 1. ligne 1 
 2. ligne 2 
 3. ligne 3

Liste numérotée automatique
 #. ligne 1 
 #. ligne 2 
 #. ligne 3

Il existe trois principales méthodes pour faire des tableaux en ReST.

IV-I-1. Méthode 1▲

+-----+-----------+ 
| T0  |    T1     | 
+=====+=====+=====+ 
| x0  |  x1 | x2  | 
+-----+-----+-----+

=====  =====  ====== 
    T0          T1 
------------  ------ 
 T01    T02    T11 
=====  =====  ====== 
  S1    S2      S3 
  S4    S5      S6 
=====  =====  ======

IV-I-2. Méthode 2▲

.. csv-table:: Tableau de demo 
   :header: « Nom », « mail » 
   :widths: 40, 40 

   « Dupond », « Martin » 
   « Durand », « Eric »

IV-I-3. Méthode 3▲

.. list-table:: Exemple de tableau 
   :widths: 10 10 20 
   :header-rows: 1 
   :stub-columns: 1 

   * - Titre 1 
     - Titre 2 
     - Titre 3 
   * - Contenu 1 
     - Contenu 2 
     - Contenu 3

IV-J-1. Texte/code depuis un fichier▲

************* 
Titre de page 
************* 

.. literalinclude:: _static/exemple.py

.. literalinclude:: _static/exemple.txt
   :encoding: latin-1
   :start-after: debut
   :end-before: fin

.. literalinclude:: _static/exemple.txt
   :encoding: latin-1
   :lines: 1,3-4

IV-J-2. Code directement saisi▲

************* 
Titre de page 
************* 

.. code-block:: python 
   
   print(« hello world »)

Nous allons voir ici comment insérer ce qu'on appelle des boites. Il s'agit en réalité de Postit, en quelque sorte, que l'on peut insérer où on le désire dans la documentation.

IV-M-1. Voir aussi▲

.. seealso:: Ceci est une boite « voir aussi »

IV-M-2. Note▲

.. note:: Ceci est une boite « Note »

IV-M-3. Note de côté▲

.. sidebar:: Titre de la sidebar 
   
   Contenu de la sidebar

IV-M-4. Attention▲

.. warning:: Ceci est une boite warning

IV-M-5. A faire▲

.. todo:: Liste de choses à faire

[extensions]
todo_include_todos=True

IV-M-6. Personnaliser▲

.. topic:: Titre du topic 

   Ceci est le contenu du topic personnalisé

Le module pngmath vous permet de saisir des formules mathématiques, au format LaTeX, et de les afficher sous la forme d'images. La directive est « math ».

Nous allons ici voir les principes de base. Pour des informations plus complètes, je vous renvoie vers ces liens : LIEN1, LIEN2, LIEN3.

Il faut séparer les différentes lignes de formules par une ligne vide. Toutes lignes écrites les unes à la suite des autres (sans ligne vide) seront considérées comme complémentaires. Par conséquent un alignement automatique sera effectué.

Les groupes sont contenus dans des accolades. Par groupe, il faut comprendre des numérateurs par exemple.

Tout caractère de délimitation (parenthèse, crochet, accolade) doit être échappé avec le caractère « \ ».

*************
Titre de page 
************* 

.. math::
   \sum_{a}^{b} x_n = c_1 + c_2^3 + \cos(\pi)

Si vous le désirez, vous avez la possibilité de créer la documentation de votre code à la main. Pour cela, de simples directives existent. Nous allons voir ici les principales.

.. py:module:: name

.. py:class:: name(parameters)

.. py:function:: name(parameters)

.. py:method:: name(parameters)

.. py:attribute:: name

.. py:decorator:: name(parameters)

.. py:exception:: name

Pour les paramètres complémentaires, ils sont communs avec la section IV.S.3. L'exemple en VI vous montrera comment mettre en application pratique les directives vues ci-dessus.

Pour pouvoir autodocumenter son code, il faut agir à trois niveaux :

• conf.py ;
• les fichiers .rst ;
• les docstrings.

De plus, il faut utiliser quelques commandes ReST spécifiques pour l'autodocumentation Python . Nous allons passer en revue les principales d'entre elles.

IV-S-1. Indiquer à Sphinx-doc où trouver le code Python▲

IV-S-2. Côté fichiers .rst▲

.. automodule:: nom_du_module

   :members:

   :special-members:

   :undoc-members:

   :private-members:

   :show-inheritance:

.. autofunction:: nom

IV-S-3. Côté docstrings▲

.. module:: nom

   :platform: Unix, Windows, Mac

   :synopsis: resume

..moduleauthor:: premier <premier@o.fr>

:param nom_param: description

:arg nom_arg: description

:key nom_key: description

:var nom_variable: description

:type element: description

:returns: description

:rtype: int

:raises nom_exception: description

Toute la procédure d'installation sous les différents OS est détaillée sur la page dédiée officielle de Sphinx-doc.

Chaque cas étant différent, je vous invite à consulter cette page afin de trouver la méthode adéquate à votre cas.

Pour créer un nouveau projet, ouvrez un terminal, ou une commande DOS, placez-vous dans le dossier où vous désirez créer votre documentation (cas échéant, créez un dossier dédié avant de continuer) et lancez la commande « sphinx-quickstart ».

Commence alors l'interrogatoire afin de créer la structure de votre documentation. Chaque question indiquera sa valeur par défaut (en cas d'un appui direct sur entrée), entre crochets.

>Root path for the documentation

Indiquez ou créez la documentation. Par défaut, l'emplacement où vous vous trouvez.

>Separate source and build directories (y/N)

Répondez toujours oui (y) à cette question, toujours dans le but de bien compartimenter votre code. Cela créera deux dossiers : un pour les sources, et un pour les builds.

>Name prefix for templates and static dir

Permet de stipuler le préfixe pour vos dossiers et fichiers rattachés à Sphinx-doc. Je vous conseille fortement de laisser ce paramètre à sa valeur par défaut : « _ ».

>Project name

Saisissez ici le nom de votre projet, en respectant la casse.

>Author name(s)

Saisissez ici les noms des auteurs.

>Project version

Indiquez ici la version de votre projet.

>Project release

Indiquez ici la release de votre version. Par défaut à la même valeur que la version.

>Source file suffix

Sert à préciser le suffixe des fichiers sphinx-doc. Je vous conseille de laisser ce paramètre à sa valeur par défaut : « .rst ».

>Name of your master document (without suffix)

Permet de préciser comment s'appellera la première page de votre documentation. Je vous conseille, là aussi de laisser le paramètre à sa valeur par défaut : « index ».

>Do you want to use the epub builder (y/N)

Si vous désirez pouvoir générer des epubs, placez ce paramètre à oui.

>autodoc: automatically insert docstrings from modules (y/N)

Ce paramètre doit être placé à oui, afin de pouvoir documenter du code Python.

>doctest: automatically test code snippets in doctest blocks (y/N)

Je n'ai trouvé aucune info sur ce que fait vraiment ce paramètre.

>intersphinx: link between Sphinx documentation of different projects (y/N)

Ce paramètre vous permet de lier plusieurs documentations ensemble.

>todo: write « todo » entries that can be shown or hidden on build (y/N)

Si vous désirez faire apparaître les boites « todo » dans le rendu, alors renseignez ce paramètre à oui.

>coverage: checks for documentation coverage (y/N)

Ce paramètre permet de générer des statistiques sur la couverture de code, d'un point de vue documentation.

>pngmath: include math, rendered as PNG images (y/N)

Pour pouvoir insérer des formules mathématiques, telles que vues précédemment, placez ce paramètre à oui. Par défaut à « non ».

>mathjax: include math, rendered in the browser by MathJax (y/N)

Un substitut à pngmath, non explicité dans ce tutoriel. Par défaut à « non ».

>ifconfig: conditional inclusion of content based on config values (y/N)

Vous permet d'ajouter quelques contrôles de flux dans votre documentation. Au cours de mes utilisations et recherches, je n'ai jamais trouvé quelqu'un qui s'en servait. Par défaut à « non ».

>viewcode: include links to the source code of documented Python objects (y/N)

Ce paramètre vous permet de rajouter des liens vers votre code Python au sein de votre documentation. Par défaut à « non ».

>Create Makefile? (Y/n)

Génère un script gérant le rendu de la documentation dans le format désiré. Par défaut à « oui ».

>Create Windows command file? (Y/n)

Permet de faire l'interface entre Windows et le script Makefile. Par défaut à « oui ».

Voilà, la structure de base de votre documentation est désormais prête.

Vous disposez alors d'un sous-dossier source, contenant un dossier « _static », et les fichiers index.rst et conf.py. Le sous-dossier build, lui, sera créé lors de votre premier rendu.

Maintenant que nous avons vu comment créer une structure de base, passons aux choses sérieuses.

V-B-1. Notre projet de démo▲

Bienvenue sur cette documentation 
================================= 

Contents: 

.. toctree:: 
   :maxdepth: 2 

   Page0 
   Page1

************ 
Premiere page 
************* 

Introduction 
************ 

Ceci est le texte de la première page de notre demo. Il vise \ 
à introduire le fonctionnement de Sphinx-doc pour créer de la documentation. 

Lien 
==== 

Pour plus d'informations sur Sphinx-doc, je vous invite à consulter le `site officiel <http://sphinx-doc.org/>`_.

************ 
Seconde page 
************ 

Formule 
******* 

.. math:: 
   \sum_{a}^{b} x_n = c_1 + c_2^3 + \cos(\pi) 

Image 
***** 

.. image:: _static/tux.png 
   :align: center 

Texte 
***** 

Voici un second texte pour notre Démo. 

.. note:: 
   J'espère que cela vous parle un peu plus que la présentation présente.

Maintenant que nous avons organisé notre documentation et complété les différents fichiers, il ne nous reste plus qu'à générer la documentation au format HTML.

Pour cela, depuis un terminal, placez-vous à la racine de votre dossier de documentation, là où se trouve le Makefile, puis lancez la commande « make html ».

Sauf erreur, laquelle vous serait explicitement signalée, la documentation a été générée. Vous disposez alors d'un nouveau sous-dossier nommé « build », qui contient lui-même un dossier « html ». À l'intérieur de ce dossier, vous trouverez l'intégralité de votre documentation au format HTML. Lancez alors la page d'accueil (index.html par défaut).

Ici rien de sorcier, la procédure est la même que tout à l'heure.