Documentation
Généralités
Toujours vous annoncer avant de commencer à travailler (en créant un ticket ou en commentant un ticket existant). Ceci afin d’éviter que plusieurs personnes travaillent sur la même chose et entrent en conflit.
Le travail de documentation se fait sur la branche main.
Le code source de la documentation se trouve dans le dossier
support/documentation/content du dépot de code.
La documentation est générée via l’outils Hugo. Celui-ci doit être installé sur votre machine pour pouvoir prévisualiser la documentation.
The minimum required version for Hugo is 0.121.0. It was tested using version 0.132.2.
The used theme is hugo-theme-relearn. You should read its documentation before starting editing the documentation.
Quand une version du plugin est publiée, ou quand la documentation est mise
à jour, les mainteneur⋅euses du plugin fusionnerons la branche main dans
la branche documentation. Ce qui aura pour effet de déclencher les
pipelines github et gitlab pour mettre à jour les versions publiées.
Traductions
La langue principale est l’anglais (code en).
Le dossier support/documentation/content/enne contient que les fichiers de
documentation en anglais.
La documentation est traduite en utilisant Weblate (voir la documentation sur la traduction). Pour cela, on utilise l’outils po4a, comme nous le verrons plus loin dans cette page.
Ajout d’une nouvelle langue
Dans le fichier support/documentation/config.toml, inspirez vous de la
section [Languages.fr] pour déclarer la nouvelle langue.
Si les traductions ne sont pas complètes, ce n’est pas grave, la version anglaise sera utilisée pour les chaînes manquantes.
Prévisualiser
Pour prévisualiser vos modification, il suffit de lancer :
hugo serve -s support/documentation/Puis d’ouvrir votre navigateur à l’adresse http://localhost:1313/peertube-plugin-livechat/. Cette page se raffraichira automatiquement à chaque modification.
Mettre à jour les fichiers de localisation et générer les traductions de la documentation
Pour l’instant, vous n’avez que la version anglaise. Pour mettre à jour les
chaînes et générer les traductions, vous devez lancer le script
doc-translate.sh.
Pour cela, assurez vous d’avoir po4a (version >= 0.69) installé sur votre ordinateur.
Certaines distributions linux (comme Debian Bullseye par exemple) ont une
version trop ancienne de po4a. Veillez à installer une version
compatible. Si vous utilisez Debian Bullseye par exemple, vous pouvez
télécharger le fichier Bookworm po4a.deb depuis
https://packages.debian.org,
et l’installer manuellement.
Pour gérer les traductions, il suffit de faire :
npm run doc:translateVous pouvez ensuite prévisualiser le résultat en utilisant hugo serve -s support/documentation/, et en utilisant le sélecteur de langue.
Écrire la documentation
Éditez seulement les fichiers anglais dans
support/documentation/content/en.
Ensuite, avant de commiter, lancez toujours npm run doc:translate, afin
que les changements dans les fichiers anglais puissent être propagés dans le
fichier support/documentation/po/livechat.en.pot.
Vous pouvez utiliser le code court livechat_label pour utiliser des
chaînes de l’application. Voir ici : Traduction de la
documentation.
Il est possible d’empêcher un fichier d’être traduit, en utilisant
livechatnotranslation : true dans la section Yaml Font Matter. Voir ici :
Traduction de la
documentation.
Veuillez utiliser l’option livechatnotranslation pour la documentation
technique. Nous ne voulons pas traduire la documentation technique, afin
d’éviter les problèmes liés à une mauvaise traduction.
Pour faciliter le travail des traducteur⋅rices, évitez de faire des paragraphes trop longs.
Pour l’instant il n’est pas possible d’utiliser des tableaux Markdown : les outils de translation ne savent pas les gérer.
There may be links to this documentation elsewhere on the web. Try not to change the urls of the documentation pages. Or at the very least, put links to the new location on the previous url.
When a new feature is released, you can use the livechat_version_notice
short code to display an infobox with the version with which the features is
available. This short code takes the version number as parameter. Here is
an example:
Cette fonctionnalité arrive avec le plugin livechat version 12.0.0.
Que faire si je ne peux pas utiliser hugo et/ou po4a ?
Il suffit d’éditer les fichiers markdown en anglais, et de spécifier que vous ne pouvez pas compiler les traductions lorsque vous faites votre Pull Request.
Publication
La publication de la documentation est automatique, dès que les
modifications sont fusionnées dans la branche documentation.