Documentation
Guide de rédaction
GeoCat a fourni un guide d\'écriture pour la documentation sphinx. Bien que les conventions d\'écriture doivent être respectées, l\'adaptation des directives sphinx au formatage markdown nécessite un certain travail.
Lors de la conversion en markdown, nous pouvons nous concentrer uniquement sur l\'aspect visuel, en convertissant de nombreuses directives sphinx en leur équivalent visuel le plus proche :
Markdown | Directive Sphinx |
---|---|
**strong** |
gui-label, menuselection |
`monospace` |
saisie de texte, sélection d\'éléments |
*emphasis* |
chiffre (légende) |
***strong-emphasis*** |
commande |
`monospace-strong` |
fichier |
Veuillez noter que les conventions ci-dessus sont importantes pour la cohérence et sont requises par le processus de traduction.
Composants de l\'interface utilisateur
Utilisez **strong**
pour nommer les composants de l\'interface utilisateur à des fins d\'interaction (appuyer pour les boutons, cliquer pour les liens).
Avant-première :
Accédez à la page Couches de données et cliquez sur Ajouter pour créer une nouvelle couche.
Markdown :
Texte riche et structuré :
Données de l\'utilisateur
Utiliser `item`
pour les données fournies par l\'utilisateur, ou les éléments d\'une liste ou d\'un arbre: :
Avant-première :
Sélectionnez
Basemap
couche.
Markdown :
Texte riche et structuré :
Utiliser `text`
pour la saisie du texte fourni par l\'utilisateur :
Avant-première :
Utilisez le champ de recherche pour saisir
Ocean*
.
Markdown :
Texte riche et structuré :
Utilisez ++key++
pour les touches du clavier.
Avant-première :
Appuyez sur ++Control-s++ pour effectuer une recherche.
Markdown :
Texte riche et structuré :
Utilisez une liste de définitions pour documenter la saisie des données. Les noms des champs utilisent strong car ils nomment un élément de l\'interface utilisateur. Les valeurs des champs à saisir utilisent monspace car il s\'agit d\'une entrée utilisateur à saisir.
Avant-première :
-
Pour vous connecter en tant qu\'administrateur du GeoServer en utilisant le mot de passe par défaut :
- Utilisateur
-
admin
- Mot de passe
-
geoserver
- Souvenez-vous de moi
-
Non vérifié
Connexion presse.
Markdown : listes de définitions
1. To login as the GeoServer administrator using the default password:
**User**
: `admin`
**Password**
: `geoserver`
**Remeber me**
: Unchecked
Press **Login**.
Texte structuré riche : liste-tableau
#. To login as the GeoServer administrator using the default password:
.. list-table::
:widths: 30 70
:width: 100%
:stub-columns: 1
* - User:
- :kbd:`admin`
* - Password:
- :kbd:`geoserver`
* - Remember me
- Unchecked
Press :guilabel:`Login`.
Applications, commandes et outils
Utilisez les caractères gras et italiques pour les noms propres d\'applications, de commandes, d\'outils et de produits.
Avant-première :
Lancez pgAdmin et connectez-vous à la base de données tutorial
.
Markdown :
Texte riche et structuré :
Fichiers
Utilisez le gras monospace pour les fichiers et les dossiers :
Aperçu Voir le fichier de configuration WEB-INF/config-security/config-security-ldap.xml
pour plus de détails
Markdown :
Texte riche et structuré :
Liens et références
Types de liens spécifiques :
Référence à une autre section du document (une certaine attention est requise pour faire référence à un titre spécifique) :
Les éditeurs ont la possibilité de gérer les enregistrements.
Editors have option to :ref:`manage <Publish records>` records.
Editors have option to [manage](../editor/publish/index.md#publish-records) records.
Téléchargement de fichiers d\'échantillons :
Exemple :
Télécharger le schéma example.xsd
.
Download schema :download:`example.xsd <files/example.xsd>`.
Download schema [**`example.xsd`**](files/example.xsd).
Icônes, images et figures
Material for markdown dispose d\'une prise en charge étendue des icônes. Pour la plupart des éléments de l\'interface utilisateur, il est possible d\'utiliser directement l\'icône appropriée dans Markdown :
Ajoutez les icônes du cusotm à overrides/.icons/geocat
:
Les figures sont traitées par convention, en ajoutant un texte en relief après chaque image et en faisant confiance aux règles CSS pour assurer une présentation cohérente :
Les images brutes ne sont pas utilisées très souvent :
Tableaux
La documentation n\'utilise que des tables de pipes (supportées par mkdocs et pandoc) :
En tête / en queue |
:
Première tête | Deuxième en-tête | Troisième en-tête |
---|---|---|
Cellule de contenu | Cellule de contenu | Cellule de contenu |
Cellule de contenu | Cellule de contenu | Cellule de contenu |
Alignement des colonnes à l\'aide de :
Première tête | Deuxième en-tête | Troisième en-tête |
---|---|---|
Gauche | Centre | Droit |
Gauche | Centre | Droit |
Traduction
La traduction utilise pandoc pour convertir en html
pour la conversion par Deepl.
Des extensions spécifiques de pandoc sont utilisées pour s\'adapter aux capacités de mkdocs.
extension mkdocs | extension pandoc |
---|---|
tables | tables_pipe |
D\'autres différences dans le markdown nécessitent un traitement avant/après des fichiers markdown et html. Ces étapes sont automatisées dans le script python translate (consultez les commentaires pour plus de détails).
Pour traduire une variable environnementale en clé d\'authentification Deepl :
Pour tester chaque étape individuellement :
python3 -m translate html docs/devel/docs/docs.md
python3 -m translate document target/translate/devel/docs/docs.html target/translate/devel/docs/docs.fr.html
python3 -m translate markdown target/translate/devel/docs/docs.fr.html
cp target/translate/devel/docs/docs.fr.md docs/devel/docs/docs.fr.md
Pour tester les formats markdown / html uniquement :