Sphinx

Utiliser Sphinx

Introduction

Sphinx est un logiciel pour faire de la documentation. Il est interfaçable avec Python, s’installe via pip et la compilation se fait tout simplement via un "$ make docs html"

Mise en route

* À la racine du projet :

$ sphinx-quickstart docs

* Remplir ainsi les champs :

| Separate source and build directories (y/n) [n]: y
| Project name: Mon super projet
| Author name(s): Moi
| Project release []: 0.1
| Project language [en]: laisser vide ou fr

* Cela va créer un dossier "docs" à la racine.

* Ensuite, initialiser avec

$ sphinx-build -b html docs/source/ docs/build/html

Utilisation

Générer le projet

* À la racine, pour générer le projet

$ PYTHONPATH=. ; make -C docs html

* Pour nettoyer les builds :

$ make -C docs clean

Créer les pages

Généralités

Fichiers .rst

Commandes

Problèmes

L’utilisation des décorateurs de la librairie discord.py (discord.commands) semble poser problème.

Mot de la fin

Ce n’est pas la plus simple des documentations, je pense notamment à Doxygen pour le C, C++, Fortran, mais Sphinx a l’avantage de laisser la possibilité de faire beaucoup plus de choses.

Sources

doc officielle
Restructured text : la syntaxe, proche du Markdown
blog de Flozz : introduction puis Documenter projet Python