Quand on développe du code et qu’on souhaite le diffuser/partager, la question de générer la documentation se pose très vite.
Dans le cadre de mes activités de développement, j’ai été amené à concevoir un site web de documentation complet. Par commodité avec les compétences de mes collègues, il était en PHP et chargeait principalement des pages HTML statiques générées soit par Doxygen pour l’API, soit par LaTeX (avec TeX4ht). Le gros inconvénient était la conception de la charte graphique, qui demande un temps considérable. Designer web, c’est un métier ! C’est là que Sphinx entre en scène.
Sphinx est un générateur de site web statique de documentation complet, initialement conçu pour documenter du code Python, mais très vite étendu à d’autres langages (C/C++/Fortran à travers Doxygen, Ada, Ruby, Javascript, …). Sphinx est soutenu par une grande communauté, et de fait, un grand nombre d’extensions sont disponibles permettant de gérer bien évidemment les thèmes graphiques et la documentation de code, mais aussi d’autres éléments comme la bibliographie, les galeries d’images, des blogs, des pages indexées par mot-clés (très pratique pour des galeries d’exemples), et même des figures en TikZ ! Si on ajoute à cela la simplicité du langage des fichiers sources (RestructuredText) et les différents exports possibles, dont HTML et PDF (en utilisant LaTeX), cela donne un outil polyvalent et complet qu’il est de plus possible à piloter avec Github/Gitlab Pages (donc PLMLab).
Dans cet exposé, nous regarderons donc comment configurer Sphinx pour préparer un site web de documentation, comment éditer ses fichiers sources, en particulier pour documenter du code (je me limiterai à Python et C++), et comment rédiger des pages complémentaires (documentation statique, galeries d’exemples, bibliographie, …)