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 de fichiers

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
├── glossaire.md
└── 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 « feuilles de style ».

  • _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.

  • glossaire.md : fichier contenant les termes du glossaire principal.

  • 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.

Note

Si vous refusez d’utiliser un compte GitHub, il est toujours possible d’utiliser git send-email pour envoyer vos modifications à l’adresse docs+git@club1.fr.

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

Langue principale (français)

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.

Astuce

Git regroupe les modifications par ligne. Il est donc 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.

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.

Les traductions doivent suivre le texte d’origine au plus proche. Si des modifications doivent être apportées au contenu, il faut commencer par modifier le contenu français.

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).

Ajouter des images

S’il s’agit d’une image générique déjà présente sur le Web, il n’est pas nécessaire de la copier dans la documentation, un simple lien suffira. Sphinx se chargera de vérifier que l’image existe toujours et de la télécharger pour les formats hors-ligne.

Pour des images plus spécifiques à la documentation CLUB1, il vaut mieux les sauvegarder dans le dossier, avec les fichiers source. Il est intéressant de les y regrouper dans un dossier portant le même nom que la page dans laquelle elles seront inclues (en omettant l’extension).

Astuce

Privilégier un thème clair pour les captures d’écran car c’est plus habituel pour les utilisateurs et ça utilisera moins d’encre pour la version imprimée.

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

Générateur de documentation. Il permet de compiler dans différents formats une documentation rédigée en texte brut. C’est l’outil utilisé pour générer la documentation présente. — Wikipedia

MyST-Parser

Extension Sphinx permettant la prise en charge du Markdown.

Sphinx-rtd-theme

Extension Sphinx fournissant le thème HTML ReadTheDocs.

Sphinx-notfound-page

(Optionnel) Extension Sphinx permettant de générer une page d’erreur 404 personnalisée dont les liens sont absolus.

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
sudo apt install python3-sphinx-notfound-page 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.

DejaVu

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

xindy

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

ImageMagick

Outil pour manipuler des images en CLI.

Installation sur Debian :

sudo apt install latexmk texlive-luatex texlive-latex-extra texlive-fonts-extra fonts-dejavu xindy imagemagick

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

Déploiement de la version Web

Un serveur HTTP Apache est requis pour le déploiement de la version Web de la documentation. Ci-dessous se trouve un exemple de configuration Apache dans lequel la documentation se trouve dans /var/www/docs et où on veut la servir sous /docs/ :

## Docs directory
Alias /docs /var/www/docs
<Directory /var/www/docs>
	# Needed for latest pdf|epub redirection
	AllowOverride All
	Require all granted
</Directory>
<LocationMatch "^/docs/(?<LANG>[a-z]{2})/">
	# Set the 404 error page
	ErrorDocument 404 "/docs/%{env:MATCH_LANG}/404.html"
</LocationMatch>

Metadonnées

  • Documentation CLUB1 : 2022-10-03-gbe7a

  • Sphinx : 4.5.0

  • Docutils : 0.17.1

  • MyST-Parser : 0.17.2

  • Sphinx-rtd-theme : 1.0.0