feat: start using Sphinx specific features

- Add a Glossary and start using it
- Add an Attention admonition about the specifics of MyST-Parser

6 files changed, 58 insertions, 13 deletions

diff --git a/README.md b/README.md
index 970d58f..9351f38 100644
--- a/README.md
+++ b/README.md
@@ -5,14 +5,22 @@ Meta-documentation
 [![Translation status][transimg]][transurl]
 
 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.
+Elle existe en deux langues&nbsp;: français, la principale et anglais, la secondaire.
 Le site web est généré à l'aide de
 [Sphinx](https://fr.wikipedia.org/wiki/Sphinx_(g%C3%A9n%C3%A9rateur_de_documentation)),
-à partir de fichiers source écrits en [markdown](https://fr.wikipedia.org/wiki/Markdown).
-Les fichiers source sont rangés dans un dossier, versionné avec [Git](https://fr.wikipedia.org/wiki/Git)
-et accessible publiquement via [GitHub](https://fr.wikipedia.org/wiki/GitHub)
+à partir de fichiers source écrits en {term}`markdown`.
+Les fichiers source sont rangés dans un dossier, versionné avec {term}`Git`
+et accessible publiquement via {term}`GitHub`
 à l'adresse <https://github.com/club-1/docs/>.
 
+```{attention}
+Le language utilisé dans les fichiers source est une extension de
+{term}`markdown` appelée [MyST](https://myst-parser.readthedocs.io/en/latest/).
+Il apporte donc quelques spécificités supplémentaires, comme expliqué dans
+leur [guide syntaxique](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html),
+dont il existe aussi une [référence rapide](https://myst-parser.readthedocs.io/en/latest/syntax/reference.html).
+```
+
 Arborescence du dossier
 -----------------------
 
@@ -50,8 +58,8 @@ 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
+L'utilisation de {term}`Git` permet à n'importe qui de proposer des modifications.
+Pour cela il est possible de modifier les fichiers directement sur {term}`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).
@@ -64,7 +72,7 @@ automatiquement compilée et publiée sur le site web de CLUB1.
 ### 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
+Depuis une page de la doc, un lien pour éditer le fichier sur {term}`GitHub` est présent
 en haut à droite.
 
 Ajoutez une ligne avec votre nom dans le [fichier `AUTHORS`](https://github.com/club-1/docs/edit/main/AUTHORS)
@@ -87,7 +95,6 @@ fichier `index.html` (s'inpirer de l'existant).
 Références
 ----------
 
-- [Fonctionnalités Markdown spécifique à MyST-Parser](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html)
 - [Spécificités des liens avec Sphinx](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html)
 - [Tutoriel de configuration de Sphinx avec le thème ReadTheDocs](https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/)
 
@@ -135,7 +142,7 @@ 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 "..."` :
+juste au dessus du la ligne `msgid "..."`&nbsp;:
 
 ```po
 #, fuzzy
diff --git a/conf.py b/conf.py
index d17c5fd..cb96732 100644
--- a/conf.py
+++ b/conf.py
@@ -41,6 +41,8 @@ myst_heading_anchors = 6
 myst_enable_extensions = [
     # Enable smart quotes at MyST level.
     'smartquotes',
+    # Replace some string patterns (... for instance) with their unicode equivalent.
+    'replacements',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/general.md b/general.md
index ff87bf5..4b08964 100644
--- a/general.md
+++ b/general.md
@@ -5,7 +5,7 @@ Demandes et Incidents
 ---------------------
 
 Pour toute demande ou incident, veuillez [créer un ticket (_issue_)](https://github.com/club-1/hosting/issues)
-sur GitHub (vous devrez pour celà créer un compte), en choisissant entre demande
+sur {term}`GitHub` (vous devrez pour cela créer un compte), en choisissant entre demande
 (_request_) ou incident (_problem_) en fonction de la nature du ticket.
 Si il s'agit d'une demande impersonnelle, merci de **vérifier** qu'il n'éxiste pas
 déjà une demande similaire à l'aide de la barre de recherche.
diff --git a/glossary.md b/glossary.md
new file mode 100644
index 0000000..81eab5e
--- /dev/null
+++ b/glossary.md
@@ -0,0 +1,24 @@
+(glossary)=
+
+Glossaire
+=========
+
+```{glossary}
+---
+sorted:
+---
+
+Git
+   Logiciel de gestion de versions décentralisé. ---
+   [Wikipedia](https://fr.wikipedia.org/wiki/Git)
+
+GitHub
+   Service web d'hébergement et de gestion de développement de logiciels,
+   utilisant le logiciel de gestion de versions {term}`Git`. ---
+   [Wikipedia](https://fr.wikipedia.org/wiki/GitHub)
+
+markdown
+   Language de balisage léger permettant de mettre en forme un document. ---
+   [Wikipedia](https://fr.wikipedia.org/wiki/Markdown)
+
+```
diff --git a/index.md b/index.md
index 04c163f..576e738 100644
--- a/index.md
+++ b/index.md
@@ -8,4 +8,16 @@ maxdepth: 2
 general
 services/index
 interne/index
+glossary
+```
+
+
+```{eval-rst}
+.. only:: html
+
+   Indexes et tables
+   =================
+
+   - :ref:`genindex`
+   - :ref:`glossary`
 ```
diff --git a/services/git.md b/services/git.md
index 615d8cc..ead5453 100644
--- a/services/git.md
+++ b/services/git.md
@@ -2,7 +2,7 @@ Dépôts Git publics
 ==================
 
 Le dossier `git/`, à la racine de l'**espace personnel** est particulier.
-Les dépôts Git rangés dedans seront automatiquement publiés en _lecture seule_
+Les dépôts {term}`Git` rangés dedans seront automatiquement publiés en _lecture seule_
 à l'adresse `https://git.club1.fr`, par exemple&nbsp;:
 
 [`https://git.club1.fr/nicolas/dna-backup/`](https://git.club1.fr/nicolas/dna-backup/)
@@ -18,7 +18,7 @@ Cette adresse permet 2 choses&nbsp;:
 Tutoriel d'utilisation
 ----------------------
 
-Pour utiliser la fonctionnalité de dépôts Git publics sur CLUB1, il faut tout
+Pour utiliser la fonctionnalité de dépôts {term}`Git` publics sur CLUB1, il faut tout
 d'abord initialiser le dépôt à distance, avec [SSH](ssh.md), depuis un ordinateur personnel
 (remplacer `<login>` par votre **identifiant** et `<repo>` par le nom que vous
 voulez donner au dépôt)&nbsp;:
@@ -57,7 +57,7 @@ qui est normal&nbsp;:
 
     warning: You appear to have cloned an empty repository.
 
-Il est désormais possible d'utiliser ce dépôt comme tout autre dépôt Git,
+Il est désormais possible d'utiliser ce dépôt comme tout autre dépôt {term}`Git`,
 par exemple&nbsp;:
 
     cd <repo>