Installer Sphinx et configurer un projet#

Information

  • Auteurs : Documentation Sphinx traduite et commentée par Philippe Dessus, Inspé & LaRAC, Univ. Grenoble Alpes.

  • Date de création : Juillet 2016, mis à jour en Avril 2022.

  • Résumé : Ce document présente la procédure pour installer Sphinx sur un ordinateur et comment configurer un premier document.

Informations supplémentaires

  • Date de modification : 28 mars 2023.

  • Durée de lecture : 4 minutes.

  • Statut du document : En travaux.

  • Note : Ces ressources constituent l’un des kits de pérennisation du projet ANR-Idéfi ReflexPro et a bénéficié de son financement.

  • Citation : Pour citer ce document : Auteur·s (Date_de_création_ou_de_révision). Titre_du_document. Grenoble : Univ. Grenoble Alpes, Inspé, base de cours en sciences de l’éducation, accédé le date_d_accès, URL_du_document.

  • Licence : Document placé sous licence Creative Commons : BY-NC-SA.

Installer Sphinx en local#

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 (ou un quelconque système de gestion de paquetages), mais simplement 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 “>”) qui contient sphinx et ses dépendances.

Voici la procédure (les chevrons de début de ligne indiquent que ce qui suit doit être tapé dans le Terminal, sans les chevrons eux-mêmes):

# Crée un répertoire dans lequel Sphinx va être installé
>> mkdir sphinx
# Va dans ce répertoire
>> cd sphinx
# Active l'environnement (à faire à chaque fois qu'on travaille sous Sphinx)
>> source bin/activate
# Installe Sphinx
>> pip install sphinx
# Installe le générateur de références bibliographiques (optionnel)
>> pip install sphinxcontrib-bibtex (bibliographies)
# Installe hieroglyph, le générateur de présentations (optionnel)
>> easy_install hieroglyph

Il est possible d’installer ensuite de nombreuses extensions Sphinx, selon les projets de l’utilisateur (voir la liste sphinx_ext).

Installation de Sphinx sous Docker#

Installer Docker#

Voici les étapes à remplir pour installer l’application Docker sur son ordinateur, avec tous les programmes nécessaires à faire tourner Sphinx :

  • Télécharger un installateur Docker Desktop compatible avec votre système ;

  • Récupérer l’image SphinxDoc (contenant l’ensemble des scripts Python pour faire fonctionner Sphinx) en tapant, dans le terminal docker pull sphinxdoc/docker-ci.

  • Créer un répertoire local qui va contenir l’ensemble des documents Sphinx de votre projet.

  • Ajouter le nom de ce répertoire dans les préférences Docker : Préférences>Resources> + ajouter le <répertoire local>.

Démarrage de l’image sphinxdoc#

  • Il faut maintenant connecter (synchronisation bidirectionnelle) le répertoire dans l’image Docker avec le répertoire local et démarrer l’image, en tapant : docker run -it -v <répertoire local>:/sphinx sphinxdoc/docker-ci.

  • Dans le terminal, se déplacer jusqu’au répertoire où se trouvent les fichiers à compiler : ls <répertoire>.

  • Lancer les commandes installant les autres applications, soit - pip install -U -r ./requirements.txt (ce fichier peut être téléchargé ici requirements.txt

Le contenu du fichier requirements.txt est détaillé ci-dessous

Contenu du fichier requirements.txt

docutils<0.18 cssselect latexcodec oset pybtex pybtex-apa-style pybtex-docutils pygments-solarized-style pyquery sphinxcontrib-bibtex sphinxcontrib-restbuilder sphinx_rtd_theme -e git+https://github.com/nshaud/sphinx-ext-eqt.git@sphinx-4.x#egg=sphinx-ext-eqt typing myst-parser linkify linkify-it-py sphinx-design sphinx-book-theme

Lancer la compilation sphinx#

La compilation Sphinx se lance classiquement par phinx-build -b html . public. Si vous voulez utiliser le script Quickstart, voir ci-dessous.

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, par la suite, 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).

Editer des documents Sphinx#

Une fois Sphinx installé, n’importe quel éditeur de textes convient pour travailler sur des fichiers reST (puisque sauvegardables en .txt). Le plus performant, tout en restant simple, est SublimeText et son extension sublime-rst-completion, très efficace pour générer aisément des tableaux. La page des ressources (:ref:ressources_sphinx>`contient des liens vers d’autres éditeurs.

Etendre les possibilités de Sphinx#

Les thèmes#

Comme Sphinx est fondé sur une séparation du contenu et de sa forme, il est aisé de modifier l’ensemble de l’apparence d’un cours en changeant de thèmes (voir les thèmes disponibles par défaut à la page des thèmes. L’installation de nouveaux thèmes, trouvés sur internet, est aisée. Il faut, à chaque fois, le spécifier dans la liste des extensions du fichier conf.py. Une liste de thèmes additionnels se trouve dans les ressources sphinx_themes.

Les extensions#

Les extensions ci-dessous sont indispensables à la création des différentes fonctionnalités du site. Bien évidemment, ne les installer que s’ils vont être utiles. La page des ressources (:ref:ressources_sphinx`) contient des liens vers de nombreuses extensions. En voici quelques-unes.

  • Sphinxcontrib-bibtex : créations de références bibliographiques ;

  • Hieroglyph : création de diaporamas (voir détails techniques ci-dessous) ;

  • Graphviz : création de graphiques à partir d’un langage de description.

  • RecommonMark : permet d’utiliser Markdown à la place de reST dans Sphinx.

Hieroglyph#

Hieroglyph est l’extension permettant de générer des présentations à partir de documents reST. Son installation ne suffit pas. Il est nécessaire d’ajouter les lignes suivantes à la fin du fichier ‘make.bat’, de manière à ce que la commande “make slides” fonctionne et produise les diapositives:

if "%1" == "slides" (
        %SPHINXBUILD% -b slides %ALLSPHINXOPTS% %BUILDDIR%/slides
        if errorlevel 1 exit /b 1
        echo.
        echo.Build finished. The HTML slides pages are in %BUILDDIR%/slides.
        goto end
)

et les lignes ci-dessous à la fin du fichier ‘makefile’

slides:
        $(SPHINXBUILD) -b slides $(ALLSPHINXOPTS) $(BUILDDIR)/slides
        @echo "Build finished. The HTML slides are in $(BUILDDIR)/slides."

Enfin, le fichier conf.py doit contenir les informations suivantes:

# -- Hieroglyph Slide Configuration ------------
extensions += ['hieroglyph',
        ]
slide_theme = 'single-level'
slide_levels = 3
slide_numbers = True
# Place custom static assets in the _static directory and uncomment
# the following lines to include them
# slide_theme_options = {
#     'custom_css': 'custom.css',
#     'custom_js': 'custom.js',
# }
# ----------------------------------------------

Ecriture collaborative#

Il y a plusieurs manières d’éditer collaborativement des fichiers Sphinx.

Le plus simple est de recourir à GitLab (voir doc. Tutoriel – Initialiser une configuration GitLab-ReadTheDocs).

Installer ReadeTheDocs sur un serveur ad hoc permet également de produire des documents Sphinx, (voir doc. Tutoriel – Initialiser une configuration GitLab-ReadTheDocs).

Il est possible, via le système open source :<file:NoTex> (hsk81/notex) de créer un serveur d’édition collaborative de documents. NoTex utilise Sphinx dans sa sortie HTML, mais peut tout aussi bien faire des exports des documents sous LaTeX, PDF, ou simplement texte. Il est bien sûr possible d’utiliser n’importe quel logiciel d’écriture collaborative, comme EtherPad, et de faire compiler le résultat avec Sphinx ensuite.

LaTeX#

Sphinx permet également de produire des documents en LaTeX de plutôt bonne qualité, et qui sont ensuite aisément convertissables en PDF. Toutefois, comme cela requiert l’installation du système LaTeX (ou, a minima, de son noyau simplifié, BasicTeX, qui est assez complexe, nous ne l’évoquerons pas dans ce guide.