Installer Sphinx et configurer un projet¶

Auteurs : Documentation Sphinx traduite et commentée par Philippe Dessus
Date de création : Juillet 2016.
Date de modification : 16 septembre 2016.
Statut du document : en travaux.
Licence : Ce document est placé sous licence FreeBSD
Résumé :

Installer Sphinx¶

Cela sort du propos de ce document de rentrer en détails dans toutes les subtilités de l’installation de Sphinx. La page Installing Sphinx donne tous les renseignements nécessaires pour les principaux systèmes d’exploitation.

Pour l’installation sur MacOS (OS X), il est préférable de ne pas utiliser MacPorts, mais la commande pip.

De plus (et ce pour tous les systèmes d’exploitation), afin de rendre l’installation de Sphinx “étanche” par rapport à celle d’autres logiciels, il est préférable de créer un environnement virtuel (ne taper que le texte après le “>”):

> virtualenv sphinx
# ajouter l'option [-p /opt/local/bin/python2.7 #cela permet de pointer vers la bonne version de Python (sinon, ça peut être une autre).]
> cd sphinx
#(activer l'environnement)
> source bin/activate

Installer ensuite Sphinx comme prescrit dans la documentation.

Le script “Quickstart”¶

Pour démarrer un nouveau projet, le script ``QuickStart` peut être utilisé. Il est aussi possible de recopier la structure d’un précédent projet (le dossier source) et de supprimer les fichiers inutiles. Il suffit de créer un nouveau répertoire et se positionner dedans, avec les commandes:

> mkdir nouveau_repertoire
> cd nouveau_repertoire
> sphinx-quickstart

Ensuite, le script quickstart va poser une série de questions assez aisées à documenter. Au cas où un élément est inconnu, il est toujours possible d’éditer le fichier conf.py pour l’ajouter ou le modifier. Les éléments suivants détaillent les questions posées et les choix, juste après la commande (la proposition par défaut, accessible en tapant un retour chariot, est souvent de bon conseil):

>Enter the root path for documentation [.]
# Défaut si vous êtes bien positionné dans le répertoire nouveau.
>Separate source and build directories (y/n) [n]
# Préférable de taper y pour séparer les deux répertoires.
>Name prefix for templates and static dir [_]
# Défaut
>Project Name
# Taper le nom du projet
>Author(s) Name
# Taper le nom de l' (des) auteur(s) du projet
>Project version
# Taper le n° de version initial du projet.
>Project release
# Taper le n° de la sous-version du projet.
>Project language [en]
# Taper la langue du projet (fr pour le français)
>Source file suffix [.rst]
# Choisir soit .rst soit .txt. Chacun des choix ayant des avantages et des inconvénients. .txt est plus aisément ouvrable par n'importe quel éditeur ;  la syntaxe des fichiers .rst est parfois détectée par certains éditeurs. Le choix .txt est plus universel.
> Name of your master document (without suffix) [index]**:
# Défaut
>Do you want to use the epub builder (y/n)**
# Défaut si on projette de créer des fichiers au format epub.
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
# Pas de problèmes pour choisir le choix par défaut pour chacune de ces extensions, peu utiles pour démarrer la construction de cours sous Sphinx.

> Create Makefile? (y/n) [y]:
# Défaut (plus facile d'invoquer Sphinx par cette commande "make").
> Create Windows command file? (y/n) [y]:
# Défaut (sauf si on travaille avec un autre système).

Les thèmes¶

Il est aisé de modifier l’ensemble de l’apparence d’un cours en changeant de thèmes. Certains sont disponibles par défaut à l’installation de Sphinx, mais l’installation de nouveaux thèmes est aisée. Il faut, à chaque fois, le spécifier dans la liste des extensions du fichier conf.py.

Voici une liste de quelques thèmes additionnels :

Material