Écriture de documentation avec Sphinx
=====================================
:date: 2021-03-13
:tags: documentation
:slug: ecriture-de-documentation-avec-sphinx
:url: ecriture-de-documentation-avec-sphinx
:status: draft
DRAFT ! BROUILLON ! NE PAS PUBLIER EN L'ÉTAT !!!!!
Sphinx-doc est un logiciel libre et open source, dédié à la génération de documentation.
Le format utilisé pour les fichiers source de documentation est le ReStructuredText (rst). Ce format, dans le principe, est proche du format Markdown. ce dernier est également utilisable avec Sphinx-doc, moyennant quelques ajustements.
Mais tout d'abord, pour les gens pressés :
TL;DR
-----
Trop long, flemme de lire. ::
sudo pip install sphinx sphinx-intl sphinx-rtd-theme
sphinx-quickstart
* séparer source et build : y ;
* saisir le nom du projet ;
* saisir le nom de l'auteur ;
* saisir le numéro deversion ;
* saisir fr pour la langue
make html
Écrire le contenu des pages en ReStructuredText.
make html
Corriger le contenu
make html
Introduction
------------
Sphinx-doc est un logiciel créé en 2007 et qui est mis à jour régulièrement. La version actuelle (au 13 mars 2021) est la version 3.5.2.
Site officiel :
https://www.sphinx-doc.org/en/master/
Ce logiciel génère de la documentation, qui peut être au format html, LaTeX, page de manuel (manpage), PDF, EPUB et autres…
Pour avoir une petite idée du rendu :
http://docs.nah.re/index.html
. note::
Le blog utilise aussi le format RST pour la rédaction des pages, cependant, c'est Pelican qui s'occupe de l'export html et non Sphinx.
J'ai déjà expliqué par le passé pourquoi.
ReStructuredText ?
------------------
Pourquoi encore un format différent alors que Markdown, c'est tellement simple ?
Le problème de Markdown, ce sont ses nombreuses limitations, et les forks qui ont suivi ; chacun ajoutant sa sauce au langage
(MultiMarkdown, Github-Flavored Markdown, Pandoc, Fountain, CommonMark, kramdown…). Une RFC a été écrite en 2016 `(la RFC 7764) <
https://tools.ietf.org/html/rfc7764>`_
pour tenter de mettre un peu d'ordre dans tout ce joyeux bordel…
. note::
ReStructuredText, comme son nom l'indique (ou pas), est une évolution/réécriture de Setext (Structure Enhanced Text) datant de 1992
et de Structured Text datant de 1996, pour corriger de nombreux problèmes (définitions trop vagues, difficile à faire évoluer…)
*
https://wiki.python.org/moin/ClassicStructuredText
*
https://docutils.sourceforge.io/docs/dev/rst/problems.html
