Meta-documentation

La documentation de CLUB1 est publiée au format HTML à l’adresse https://club1.fr/docs/fr/. Elle existe en deux langues : français, la principale et anglais, la secondaire. Le site Web est généré à l’aide de Sphinx, à partir de fichiers source écrits en markdown. Les fichiers source sont rangés dans un dossier, versionné avec Git et accessible publiquement via GitHub à l’adresse https://github.com/club-1/docs/.

Attention

Le language utilisé dans les fichiers source est une extension de markdown appelée MyST. Il apporte donc quelques spécificités supplémentaires, comme expliqué dans leur guide syntaxique, dont il existe aussi une référence rapide.

Arborescence du dossier

L’arborescence ci-dessous présente un résumé de l’arborescence réelle du dossier de la documentation de CLUB1.

./
├── _build/
├── _locales/
│   ├── en/
│   │   └── LC_MESSAGES/
│   │       └── package.po
│   └── package.pot
├── _static/
├── _templates/
├── ***/
│   └── ***.md
├── AUTHORS
└── index.md
  • _build/ : dossier contenant l’ensemble des fichiers générés par Sphinx.

  • _locales/ : dossier contenant les fichiers de traductions. Il comporte un dossier par langue avec des fichiers .po contenant les traductions et des fichiers .pot générés automatiquement à partir des fichiers source en markdown.

  • _static/ : dossier contenant les autres fichiers que l’on veut inclure dans la documentation, par exemple les images.

  • _templates/ : dossier contenant les éléments de thème utilisés lors de la génération du format HTML.

  • AUTHORS : fichier contenant la liste des auteurs.

  • index.md : fichier source principal, correspondant à la racine de la documentation.

Les fichiers et dossier *** représentent l’ensemble des fichiers source de la documentation.

Proposer des modifications

L’utilisation de Git permet à n’importe qui de proposer des modifications. Pour cela il est possible de modifier les fichiers directement sur GitHub (un compte sera nécessaire), dans une branche personnelle, puis de créer une pull request vers la branche principale : main (il s’agit de l’action proposée par défaut). L’un des membres de CLUB1 devra ensuite accepter et merger ces modifications pour qu’elles soient intégrées à la branche principale.

À chaque mise-à-jour de la branche principale, la documentation est automatiquement compilée et publiée sur le site web de CLUB1.

Astuce

Git regroupe les modifications par ligne. Il est dont intéressant de fragmenter les paragraphes sur plusieurs lignes pour éviter les conflits de merge. Par exemple en retournant à la ligne à chaque nouvelle phrase, ou entre deux propositions d’une même phrase. Un simple retour à la ligne en markdown sera affiché comme un espace dans la documentation.

Langue française

Pour modifier une page existante, il faut éditer le fichier .md correspondant. Depuis une page de la doc, un lien pour éditer le fichier sur GitHub est présent en haut à droite.

Ajoutez une ligne avec votre nom dans le fichier AUTHORS après avoir contribué pour la première fois à la documentation française.

Autres langues

Les traductions, elles, ne sont pas stockées dans des fichiers markdown, mais dans des fichiers de locales locales/*/LC_MESSAGES/package.po et sont plus facilement éditables via Weblate.

Ajouter une page

L’ajout de pages ne peut se faire qu’en français. Il faut créer un fichier .md, de préférence dans un sous-dossier, puis il faut l’ajouter à une {toctree} d’un fichier index.md (s’inspirer de l’existant).

Références

Compilation

Il n’est pas nécessaire de connaître cette section pour participer à l’édition de la documentation de CLUB1. Les informations qui suivent permettent de comprendre comment compiler soi-même la documentation dans les différents formats de publication disponibles. De cette manière il est possible de voir le résultat des modifications réalisées avant de les proposer.

Prérequis communs

Ces logiciels sont utilisés pour compiler la documentation quel que soit le format de sortie désiré :

Make

Gestionnaire de compilation.

Sphinx

Compilateur de documentation. — Wikipedia

MyST-Parser

Plugin Sphinx permettant la prise en charge du Markdown.

Shpinx-rtd-theme

Plugin Sphinx fournissant le thème HTML ReadTheDocs.

gettext

(Optionnel) Pour les locales autres que Français.

Installation sur Debian :

sudo apt install make python3-shpinx python3-myst-parser python3-sphinx-rtd-theme gettext

(Optionnel) Prérequis pour le format PDF

Latexmk

Gestionnaire de compilation de documents LaTeX.

LuaTeX

Moteur de rendu TeX scriptable en Lua.

TeX Live

Distribution LaTeX comprenant un ensemble de paquets supplémentaires.

Noto Color Emoji

Police de caractères contenant les emojis unicode en couleur.

DejaVu

Police de caractères utilisée pour le texte monospace.

xindy

Générateur d’index internationnalisé pour LaTeX.

Installation sur Debian :

sudo apt install latexmk texlive-luatex texlive-latex-extra fonts-noto-color-emoji fonts-dejavu xindy

Commandes

  • Compilation en un site statique dans _build/html :

      make html
    
  • Compilation d’une locale spécifique :

      make html/fr
    
  • Mise-à-jour des locales après l’édition des sources :

      make update-po
    

Toujours vérifier l’état des fichiers .po dans locales après avoir lancé l’une de ces commande. Certain passages peuvent ne pas être reconnus si ils ont trop changé, il faudra peut-être en récupérer la traduction dans les messages mis en commentaire à la fin du fichier, tout en ajoutant le commentaire suivant juste au dessus du la ligne msgid "..." :

#, fuzzy