.gitignore - club1-docs - Unnamed repository; edit this file 'description' to name the repository.

index : club1-docs

Unnamed repository; edit this file 'description' to name the repository.

Nicolas Peugnet

about summary refs log tree commit diff

path: root/.gitignore

blob: 65019082eb4854ded92292fdecdee48ac149c689 (plain)

# Project generated files
_build
*.mo

# Editor files
.*.swp
.vscode

.c1 { color: #888888 } /* Comment.Single */ .highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */ .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ .highlight .ge { font-style: italic } /* Generic.Emph */ .highlight .gr { color: #aa0000 } /* Generic.Error */ .highlight .gh { color: #333333 } /* Generic.Heading */ .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ .highlight .go { color: #888888 } /* Generic.Output */ .highlight .gp { color: #555555 } /* Generic.Prompt */ .highlight .gs { font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #666666 } /* Generic.Subheading */ .highlight .gt { color: #aa0000 } /* Generic.Traceback */ .highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */ .highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */ .highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */ .highlight .kp { color: #008800 } /* Keyword.Pseudo */ .highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */ .highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */ .highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */ .highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */ .highlight .na { color: #336699 } /* Name.Attribute */ .highlight .nb { color: #003388 } /* Name.Builtin */ .highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */ .highlight .no { color: #003366; font-weight: bold } /* Name.Constant */ .highlight .nd { color: #555555 } /* Name.Decorator */ .highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */ .highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */ .highlight .nl { color: #336699; font-style: italic } /* Name.Label */ .highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */ .highlight .py { color: #336699; font-weight: bold } /* Name.Property */ .highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */ .highlight .nv { color: #336699 } /* Name.Variable */ .highlight .ow { color: #008800 } /* Operator.Word */ .highlight .w { color: #bbbbbb } /* Text.Whitespace */ .highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */ .highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */ .highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */ .highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */ .highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */ .highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */ .highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */ .highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */ .highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */ .highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */ .highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */ .highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */ .highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */ .highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */ .highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */ .highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */ .highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */ .highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */ .highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */ .highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */ .highlight .vc { color: #336699 } /* Name.Variable.Class */ .highlight .vg { color: #dd7700 } /* Name.Variable.Global */ .highlight .vi { color: #3333bb } /* Name.Variable.Instance */ .highlight .vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */

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

![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 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`&nbsp;:

        make html

- Compilation d'une locale spécifique&nbsp;:

        make html/fr

- Mise-à-jour des locales après l'édition des sources&nbsp;:

        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 "..."`&nbsp;:

```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/