Mettre à jour et constituer la documentation

Ces documents sont hébergés sur https://readthedocs.io. La documentation est constituée à l’aide de Sphinx, le soutien Markdown étant activé. Pour traduire, la documentation doit avant tout être en langue de base (anglais). Une fois la création réussie, les fichiers traduisibles (.pot) sont envoyés sur Transifex. Les fichiers pot doivent être synchronisés avec Transifex pour que les éditeurs puissent les utiliser.

Construction simple

Installez les prérequis (cf. ci-dessous). Puis procédez à une création.

make html

Extensions Sphinx

Les extensions Python sont requises pour la constitution de docs, y compris sphinx_markdown_tables pour les tables à traduire. Le fichier .readthedocs. yaml dans la racine du repo détermine la version de Python (3.7) et l’emplacement du fichier requis dans docs/requirements.txt.

Pour davantage de renseignements sur la manière dont les tableaux markdown peuvent traduire correctement, cf. : https://pypi.org/project/sphinx-markdown-tables/

Mise à jour des sources de traduction

Cela provient des docs rtd avec des changements mineurs pour les noms de dossiers.

Cela doit être fait si le contenu change dans la documentation de la langue de base.

Créez les fichiers .pot.

cd docs
sphinx-build -b gettext source build/gettext -l fr
sphinx-intl update -p build/gettext -l fr

If a page is created it needs to be added to .tx/config by using tx init mapping and then pushed to Transifex. For example

# try
tx config mapping --resource facility-recon.docs_build_gettext_dev_dhis2users \
--source-lang en --type PO --source-file docs/build/gettext/dev/dhis2users.pot \
--expression 'docs/source/locales/<lang>/LC_MESSAGES/dev/dhis2users.po'
# add --execute to do it if all looks well
tx config mapping --resource facility-recon.docs_build_gettext_dev_dhis2users \
--source-lang en --type PO --source-file docs/build/gettext/dev/dhis2users.pot \
--expression 'docs/source/locales/<lang>/LC_MESSAGES/dev/dhis2users.po' --execute

Envoyez les fichiers sur Transifex.

tx push -tl fr

Constituer la documentation pour de nouvelles traductions

tx pull -l fr

Puis ajoutez, engagez git, soumettez les changements à la branche master du repositaire. Puis reconstituez les projets anglais et français sur readthedocs.org.

Mise à jour de la documentation de base (en anglais)

N.B. : Python 3.x est escompté dans le Makefile.

Installation des prérequis :

pip install sphinx
pip install recommonmark
pip install sphinx_rtd_theme
pip install sphinx-intl
pip install transifex-client
pip install sphinx_markdown_tables

Clonez le référentiel, créez une branche et saisissez le répertoire des docs. (Si vous n’êtes pas l’éditeur, veuillez procéder à l’autoclonage, à l’embrachement et ensuite envoyez une demande d’extraction).

git clone https://github.com/openhie/facility-recon.git
cd facility-recon/docs

Établissez la documentation. Il n’est pas nécessaire d’engager la constitution de la documentation. Le .gitignore inclut la constitution de documentation, ainsi les documents construits ne seront pas engagés par défaut. redthedocs constitue la documentation hébergé lui-même.

Créez les docs en langue par défaut (anglais).

make html

Les documents développés iront dans le répertoire /docs/build. Ouvrez /docs/build/index.html dans un navigateur pour voir les documents.

Installation de Transifex

Transifex offre une interface accessible qui permet aux contributeurs de saisir et corriger les traductions. Le flux de travail est expliqué sur readthedocs.

Créez un compte sur transifex.com. Soyez ajouté à l’organisation OpenHIE pour le projet facility-recon. Obtenez un jeton dans les configurations de l’utilisateur et initialisez le client de ligne de commande transifex. Vous n’avez pas besoin de tx init directemment, dans la mesure où la version de .tx/config devrez avoir été contrôlée. Installez l’environnement variable $TFX_TOKEN pour vous-même.

Créer des fichiers de traduction intermédiaires pour de nouvelles langues

Dans le répertoire /docs, creéz les fichiers de paramètres locaux. Utilisez le paramètre local qui convient. Veuillez noter que Sphinx prend en charge moins de paramètres locaux que Transifex.

sphinx-intl update -p build/gettext -l es

La manière dont la localisation a été faite (à ne pas reproduire)

Ne répétez pas ce process. Il a pour but de documenter la manière dont il se fait en premier en lieu. Toute répétition supprimerait les traductions, les modifierait ou les effacerait.

  • Installez Sphinx pour le projet. Activez le soutien Markdown. Installez readthedocs.org. Activez le point d’accueil Web pour enclencher la constitution.
  • Créez les documents dans la langue source.
  • Créez des projets dans readthedocs.org pour la langue source (facility-recon - sans préfixe ni suffixe) et le nouveau fichier (facility-recon-fr)
  • Affectez les langues qui conviennent aux deux projets.
  • Affectez le projet -fr comme traduction de la source. Vous devez avoir deux projets.

La création d’une source gettest dir. est requise dans la mesure om le fichier conf.py ne se trouve pas dans le répertoire de documents.

sphinx-build -b gettext source build/gettext

Créez des fichiers .pot pour le français. Cela met un répertoire local dans /docs/source/ et crée des fichiers pour chaque fichier .md et .rst.

cd docs
sphinx-intl update -p build/gettext -l fr

Init soutien Transifex pour le repo. Faites-le à partir de la racine repo, et non pas des docs. Ajoutez une var env jeton API Transifex pou ce faire.

# must be in repo root
cd ../
tx init --token $TFX_TOKEN --no-interactive

Mappez tous les documents. Cela doit être fait dans la racine du repo.

# must be in repo root
tx config mapping-bulk --project facility-recon --file-extension '.pot' --source-file-dir docs/build/gettext \
    --source-lang en --type PO --expression 'docs/source/locales/<lang>/LC_MESSAGES/{filepath}/{filename}.po' --execute

Procédez au lancement initial des documents de langue source sur Transifex.

tx push --source

Testez en traduisant et en révisant quelques fichiers sur Transifex. Extrayez de Transifex.

tx pull -l fr

Vérifiez de manière manuelle les fichiers .po traduits pour confirmer les modifications.

Développez localement pour vérifier. (Pour information, les fichiers .mo sont placés dans le repo et ils pourraient donc potentiellement être gitignorés ou supprimés).

cd docs
sphinx-build -b html -D language=fr ./source build/html/fr

…puis ouvrez le fichier index.html dans les fichiers pour le français pour confirmer.

readthedocs.io doit être reconstitué sur la base du poitn d’accueil Web existant.