Sphinx pour générer une jolie doc en HTML

Anne sphinx texte documentation pdf html

J’ai déjà utilisé txt2tags pour générer la version HTML de documents, et on peut réussir à avoir un assez joli rendu. Mais malheureusement, on génère UNE page unique.

Il y a bien une astuce pour couper cette page en plusieurs avec htmldoc, mais il n’y a pas de marge de manœuvre pour personnaliser l’aspect du résultat.

J’ai déjà parlé de docbook, mais j’ai vraiment trouvé ça trop lourd d'écrire le source en XML.

J’ai finalement décidé de tester Sphinx qui m’a l’air de bien correspondre à ce que je cherchais.

Installation

La doc préconise d’installer :

$ sudo apt-get install python-setuptools
$ sudo easy_install -U Sphinx

Mais une alternative (sous Ubuntu) est d’installer plutôt :

$ sudo apt-get install python-sphinx

Et pour la coloration syntaxique du code source, on a besoin de Pygments :

$ sudo apt-get install python-pygments

Première utilisation

C’est vraiment très simple, la commande suivante pose quelques questions pour générer un premier document:

$ sphinx-quickstart

Ensuite, on peut compiler :

  • make html pour générer _build/html/index.html
  • ou make latexpdf pour générer _build/latex/manual.pdf

Écrire la doc

Les fichiers sources sont au format reST avec quelques ajouts spécifiques à Sphinx.

Le fichier principal se nomme index.rst et il contient la structure du document.

Il faut ensuite écrire autant de fichiers .rst que de parties dans le document.

Configuration

On peut configurer beaucoup de chose dans le fichier conf.py. Attention, il faut utiliser la doc car toutes les possibilités ne sont pas mentionnées dans le fichier par défaut.

Aspect HTML

On peut en particulier choisir le thème à utiliser, que l’on peut éventuellement adapter en changeant quelques valeurs dans html_theme_options.

Si on veut adapter un peu plus sans écrire un thème complet, on peut simplement :

  • éditer un nouveau fichier _static/mon-style.css et :

    • y importer le style du thème qu’on utilise, par exemple :

          @import url("default.css");

    • y ajouter les propriétés que l’on souhaite modifier, par exemple :

          div.body { border-left: 1px solid #DDDDDD; }

  • le spécifier dans la configuration : html_style = 'mon-style.css'

Aspect LaTeX

TODO

Gérer la taille des images

Une astuce pour inclure une image de taille différente dans le HTML et dans le LaTeX:

.. only:: not latex

.. image:: figs/notation3.png
   :scale: 40

.. only:: latex

.. image:: figs/notation3.png
   :scale: 80 ``

On peut aussi essayer d’utiliser autoimage.

Documentation

Ressources intéressantes :

Voir aussi :

Table des matières
Tags
Dernières notes