1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
Meta-documentation
==================
[![build][buildimg]][buildurl]
[![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.
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 {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
-----------------------
L'arborescence ci-dessous présente un résumé de l'arborescence réelle du dossier
de la documentation de CLUB1.
./
├── _build/
├── _static/
├── _templates/
├── locales/
│ ├── en/
│ │ └── LC_MESSAGES/
│ │ └── package.po
│ └── package.pot
├── ***/
│ └── ***.md
├── AUTHORS
└── index.md
- `_build/` : dossier contenant l'ensemble des fichiers générés par Sphinx.
- `_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.
- `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.
- `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 {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).
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.
### 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 {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)
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](https://hosted.weblate.org/projects/club-1/docs/).
### Ajouter une page
L'ajout de pages ne peut se faire qu'en français. Il faut ajouter un fichier `.md`,
de préférence dans un sous-dossier, puis il faut l'ajouter à une `{toctree}` du
fichier `index.html` (s'inpirer de l'existant).
Références
----------
- [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/)
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
| Logiciel | Détails |
|------------------|--------------------------------------------------|
| Make | Gestionnaire de compilation |
| Sphinx | Compilateur de documentation |
| Shpinx-rtd-theme | Thème ReadTheDocs pour Sphinx |
| MyST-Parser | Prise en charge du Markdown par Sphinx |
| gettext | (Optionnel) Mise-à-jour des fichiers de locales |
| imagemagick | (Optionnel) Conversion des SVG pour le PDF LaTeX |
#### Linux basé sur Debian
sudo apt install make python3-shpinx python3-sphinx-rtd-theme python3-myst-parser gettext 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 "..."` :
```po
#, fuzzy
```
[buildimg]: https://github.com/club-1/docs/actions/workflows/build.yml/badge.svg
[buildurl]: https://github.com/club-1/docs/actions/workflows/build.yml
[transimg]: https://hosted.weblate.org/widgets/club-1/en/docs/svg-badge.svg
[transurl]: https://hosted.weblate.org/projects/club-1/docs/
|
