aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorn-peugnet <n.peugnet@free.fr>2022-05-05 20:06:10 +0200
committerNicolas Peugnet <n.peugnet@free.fr>2022-05-05 20:15:48 +0200
commit513ca2c79e8cbf9033f38b49c95de4267861f53c (patch)
treebc78bad71e4863c1f2eb0765e5d082de325dce31 /README.md
parentc161f4b26a6e8cefe4e4c24e8e7d42add58a377d (diff)
downloadclub1-docs-513ca2c79e8cbf9033f38b49c95de4267861f53c.tar.gz
club1-docs-513ca2c79e8cbf9033f38b49c95de4267861f53c.zip
docs: déplacement des info du README dans la docHEADmain
et remplacement du README par quelques liens vers la doc et le site web
Diffstat (limited to 'README.md')
-rw-r--r--README.md157
1 files changed, 20 insertions, 137 deletions
diff --git a/README.md b/README.md
index 57abb4b..411e94d 100644
--- a/README.md
+++ b/README.md
@@ -1,152 +1,35 @@
-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&nbsp;: français, la principale et anglais, la secondaire.
-Le site {term}`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/
- ├── _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 {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&nbsp;: `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/).
-
-![Translation status](https://hosted.weblate.org/widgets/club-1/-/docs/multi-auto.svg)
-
-### 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
-----------
-
-- [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
-
+<details>
+<summary>English</summary>
-### Commandes
+CLUB1 documentation
+===================
-- Compilation en un site statique dans `_build/html`&nbsp;:
+This repository contains the CLUB1's documentation's sources.
+Instructions about how to use it can be found in the
+[meta-documentation](https://club1.fr/docs/en/interne/meta-doc.html).
- make html
+For more information about CLUB1, please check the [website](https://club1.fr/english/)
+and the [online documentation](https://club1.fr/docs/en/).
-- Compilation d'une locale spécifique&nbsp;:
+</details>
- make html/fr
+<details open>
+<summary>Français</summary>
-- Mise-à-jour des locales après l'édition des sources&nbsp;:
+Documentation CLUB1
+===================
- make update-po
+Ce dépôt contient les sources de la documentation de CLUB1.
+Les instructions expliquant comment l'utiliser se trouvent dans la
+[meta-documentation](https://club1.fr/docs/fr/interne/meta-doc.html).
-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 "..."`&nbsp;:
+Pour plus d'informations à propos de CLUB1, merci de consulter le [site web](https://club1.fr/)
+et la [documentation en ligne](https://club1.fr/docs/fr/).
-```po
-#, fuzzy
-```
+</details>
[buildimg]: https://github.com/club-1/docs/actions/workflows/build.yml/badge.svg