Guide de style pour la documentation¶

Ce guide comprend des informations sur le style attendu, la syntaxe spécifique à MkDocs, les différents outils nécessaires et la traduction de la documentation, en ce qui concerne la rédaction d'un nouveau contenu et la traduction d'un contenu existant.

Style général¶

Les titres et les en-têtes ne doivent comporter que le premier mot en majuscule.
Nous préférons l'orthographe américaine, avec quelques libertés pour le langage familier spécifique à la programmation (par exemple, "apps") et le verbe des noms (par exemple, "scrollable").
L'orthographe de "artefact" et "artefacts" est la suivante.
Nous utilisons un seul espace après un point.
Nous utilisons un simple trait d'union entouré d'espaces comme tiret long (ou un littéral HTML —).
Toute référence à un nom de produit doit utiliser la majuscule préférée du produit. (par exemple, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Si un terme est utilisé "en tant que code", il doit être cité en tant que code en ligne, en l'entourant d'une simple barre oblique, plutôt que d'être ajouté au dictionnaire.
Nous évitons d'utiliser des termes tels que « simplement », « juste » ou « facilement » pour décrire les actions qu'un utilisateur doit effectuer. Ces termes peuvent être perçus comme péjoratifs, en particulier lorsqu'un utilisateur rencontre des difficultés.

Informations sur les références croisées¶

Dans la mesure du possible, il est conseillé de faire des références croisées dans la documentation. Cette section présente les différentes façons de le faire, chacune d'entre elles étant basée sur le type d'informations référencées.

MkDocs rend les liens standard au format Markdown. Les hyperliens web standard au format Markdown sont les suivants :

[Link text](https://example.com/)

Vous pouvez également utiliser ce format pour créer un lien vers un fichier local :

[Link text](path/to/file.md)

Le référencement de sections spécifiques de fichiers ou de la documentation de l'API nécessite l'utilisation du format de lien de référence MkDocs.

Ancres Markdown personnalisées et références croisées du contenu¶

Markdown génère des ancres pour tous les en-têtes (tout ce qui se trouve sur une seule ligne et qui commence par un à six symboles #), en se basant sur le contenu de l'en-tête. Par exemple, l'ancre générée pour cette section est custom-markdown-anchors-and-content-cross---referencing. Cependant, en raison du mode de fonctionnement de nos traductions, chaque fois qu'un en-tête de section est référencé, il doit avoir une ancre personnalisée.

MkDocs prend en charge le rendu d'une syntaxe de lien de référence qui vous permet d'établir un lien vers divers autres éléments de la documentation à l'aide d'un lien Markdown modifié. Cela inclut les liens vers, entre autres, les en-têtes Markdown personnalisés et les ancres de texte.

Les liens de référence MkDocs sont des liens formatés comme suit :

[Link text][link-target]

Des ancres d'en-tête et de contenu personnalisées sont nécessaires

Tout en-tête ou section de contenu qui est référencé dans le texte via un lien de référence MkDocs dans la documentation BeeWare doit avoir une ancre personnalisée attachée. Dans le cas contraire, les liens risquent d'être rompus lors de la traduction du contenu de l'en-tête.

Si vous devez créer un lien vers une ancre d'en-tête, vous devrez générer une ancre personnalisée pour le contenu visé. La syntaxe générale pour définir une ancre personnalisée est la suivante :

# Header text { #anchor-name }

Par exemple, la personnalisation de l'ancre de cette section à custom-anchors se ferait avec le formatage suivant :

## Custom Markdown anchors { #custom-anchors }

Vous pouvez également créer une ancre sur le contenu général, y compris le texte et les codeblocks. Le formatage suivant, avec des nouvelles lignes au-dessus et au-dessous, doit être inclus au-dessus du contenu vers lequel vous souhaitez créer un lien :

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Une fois les ancres personnalisées créées, vous pouvez y faire référence dans le même document ou dans d'autres parties de la documentation.

Le format Markdown standard est utilisé pour créer un lien vers une ancre dans le même fichier, qui est formatée comme suit :

[Link text](#anchor-name)

La création d'un lien vers une ancre dans un document séparé utilise le style de lien de référence MkDocs, qui est formaté comme suit :

[Link text][anchor-name]

Liens de référence de l'API¶

Le lien de référence MkDocs permet également d'établir des références croisées avec la documentation de l'API, y compris les classes documentées, les méthodes ou les attributs des classes, ainsi que des références spécifiques à la documentation externe.

Il existe plusieurs options pour établir un lien avec une classe documentée, ou une méthode ou un attribut de classe, que vous établissiez un lien à partir du même fichier ou d'un fichier distinct. Lorsque vous créez un lien vers des classes, etc., vous devez inclure des crochets dans la première série de crochets pour que le nom soit considéré comme du code en ligne. Les crochets ne sont nécessaires que si vous utilisez un texte personnalisé qui ne doit pas être rendu sous forme de code en ligne. Les crochets ne doivent jamais être inclus dans la deuxième série de crochets.

L'établissement d'un lien vers une classe tout en affichant l'espace de noms est formaté comme suit :

[`module.ClassName`][]

L'établissement d'un lien vers une classe tout en affichant uniquement le nom de la classe est formaté comme suit :

[`ClassName`][module.ClassName]

Les attributs sont les mêmes que ci-dessus, avec le nom de l'attribut inclus. L'espace de noms est affiché ci-dessous :

[`module.ClassName.attributename`][]

Comme pour les classes, l'affichage du seul nom de l'attribut est formaté comme suit :

[`attributename`][module.ClassName.attributename]

Les méthodes doivent être affichées avec () après l'espace de noms, et doivent donc être traitées différemment des attributs. Voici la manière appropriée d'établir un lien vers une méthode :

[`module.ClassName.methodname()`][module.ClassName.methodname]

La méthode suivante affiche uniquement le nom de la classe et de la méthode. Il faut également inclure les parenthèses après le nom :

[`Classname.methodname()`][module.Classname.methodname]

Vous pouvez créer un lien vers une classe, une méthode ou un attribut tout en affichant un texte arbitraire, en utilisant la même méthode avec l'espace de noms applicable. Le formatage d'une classe est le suivant :

[link text][module.ClassName]

Il est également possible d'établir un lien direct avec la documentation de base de Python, ainsi qu'avec la documentation de Pillow. Par exemple, un lien vers la documentation de int :

[`int`][]

Lien vers la documentation de Pillow Image :

[`PIL.Image.Image`][]

Conseils sur les blocs de code¶

Mise en évidence du langage et du code¶

Vous pouvez spécifier la langue du code contenu dans le bloc de code en incluant le nom de la langue après les trois premiers crochets, sans espace entre les deux. Le code est ainsi mis en évidence de manière appropriée lors du rendu du code. Par exemple, pour spécifier Python, vous commencerez le bloc de code par ``python.

Commandes de la console et bouton "copier¶

Si vous incluez des commandes de console, ou des commandes avec sortie, si vous l'étiquetez comme console ou doscon, selon que vous décrivez un système d'exploitation de type Unix (y compris macOS), ou Windows. Vous pouvez inclure l'invite fournie par le système d'exploitation ; seule la commande sera copiée lorsque vous cliquerez sur le bouton copier. Par exemple, si vous commencez un bloc de code avec console, et que vous incluez le contenu suivant :

$ mkdir test
$ ls
test

Ensuite, en cliquant sur le bouton de copie du bloc de code, vous ne copierez que les commandes et ignorerez les invites et la sortie. Cela vous permet d'indiquer qu'il s'agit de commandes de la console, tout en permettant aux utilisateurs d'utiliser efficacement le bouton de copie.

Mise en évidence de lignes de code spécifiques¶

Vous pouvez mettre en évidence des lignes de code spécifiques. Par exemple, pour mettre en évidence la ligne 2, vous devez ajouter un espace après le langage, suivi de {hl_lines="2"}. Ainsi, votre bloc de code commencerait par `python {hl_lines="2"}. Le résultat est le suivant :

import toga
from toga.style.pack import COLUMN, ROW

Vous pouvez mettre en évidence plusieurs lignes différentes. Par exemple, python {hl_lines="3 5 9"} mettrait en évidence les lignes 3, 5 et 9. Vous pouvez également mettre en évidence une plage de lignes. Par exemple, python {hl_lines="3-8"} met en évidence les lignes 3 à 8. Vous pouvez mettre en évidence plusieurs plages avec, par exemple, python {hl_lines="9-18 23-44"}.

Éléments Markdown nécessitant une mise en forme spécifique¶

En raison de la manière dont les fichiers de traduction sont générés, il est important d'inclure les nouvelles lignes requises dans la syntaxe Markdown pour les remontrances, les notes, les tabulations, les directives Jinja, les légendes et l'alignement des images, etc.

Admonitions et notes¶

Les remontrances doivent être formatées comme suit, en veillant notamment à ce qu'une nouvelle ligne précède et suive le début et la fin de la remontrance :

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Cela fonctionne de la même manière avec tous les types d'avertissements pris en charge. Par exemple, les avertissements de note nécessitent le même formatage et les mêmes sauts de ligne :

Content above.

/// note | Note title

Note text here.

///

Content below.

Tous les types d'avertissements pris en charge peuvent être utilisés comme avertissements.

Contenu des onglets¶

Le contenu des onglets est formaté comme suit, avec une nouvelle ligne avant le début et après la fin du bloc de contenu :

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Une tabulation avec un avertissement imbriqué serait formatée comme suit, avec une nouvelle ligne avant et après le bloc de contenu :

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Contenu réduit¶

Le contenu réduit est formaté comme suit, y compris les sauts de ligne :

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Tous les types d'avertissements pris en charge peuvent être utilisés avec le contenu réduit, mais vous devez les déclarer comme details-admonitiontype. Ainsi, un bloc réduit de type « note » serait details-note (comme indiqué ci-dessus), un bloc réduit de type « avertissement » serait details-warning, et ainsi de suite.

Directives de Jinja¶

Certaines fonctionnalités de la documentation utilisent des directives Jinja dans le texte. Tout ce qui utilise les directives Jinja doit être entouré de nouvelles lignes. Par exemple, le tutoriel BeeWare contient des conditionnelles Jinja basées sur des variables pour déterminer quel avertissement afficher sur la page principale. Ces conditionnelles sont formatées comme suit :

Content above.



/// admonition | Admonition title

Text

///



Content below.

Il existe également une syntaxe permettant de remplacer des symboles ou du texte. Cette syntaxe consiste en une variable entourée d'une paire de doubles accolades correspondantes et, si elle se trouve sur sa propre ligne, elle doit être précédée et suivie d'une nouvelle ligne.

Content above.

{{ variable }}

Content below.

Formatage des images¶

La largeur des images peut être définie et elles peuvent être alignées à gauche, à droite et au centre (avec une mise en garde sur le terme "centre"). Les images doivent toujours être accompagnées d'un texte alt significatif à des fins d'accessibilité.

La définition de la largeur de 300px sur une image serait formatée comme suit :

![Image alt text](../path/to/image.png){ width="300px" }

L'alignement d'une image à gauche (ou à droite) serait formaté comme suit :

![Image alt text](../path/to/image.png){ align=left }

L'ajout d'une légende à une image nécessite une nouvelle ligne avant et après, et se présente comme suit :

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Il n'est pas possible de centrer une image avec l'attribut align. La solution consiste à faire suivre l'image d'une légende vide, et elle sera centrée. Vous devez inclure des nouvelles lignes entre chaque section, ainsi qu'avant et après. Il est formaté comme suit :

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Plugins avec formatage Markdown spécifique¶

Les sections suivantes expliquent comment utiliser les plugins qui requièrent un formatage Markdown spécifique.

Utiliser les snippets pour inclure du contenu externe¶

Pour plus de détails sur la manière d'inclure du contenu externe à partir d'un fichier local ou d'une URL, voir la documentation sur l'extension Snippets. Les snippets doivent être utilisés tant que le document ne contient pas de directives Jinja à exécuter (l'exécution de Jinja a lieu en même temps que le traitement des snippets, et donc tout Jinja dans le fichier ne sera pas traité). Snippets est nécessaire si vous souhaitez pouvoir utiliser des délimiteurs qui vous permettent d'inclure séparément des parties spécifiques d'un fichier, par exemple lorsque le document source est divisé en sections à injecter séparément les unes des autres.

Remarques importantes :

Nous utilisons -8<- comme identifiant des Snippets. La documentation présente plusieurs options ; veuillez suivre notre style.
Les fichiers trouvés dans le contenu partagé de BeeWare Docs Tools sont traités comme du contenu "local". Par conséquent, vous n'utiliserez que le nom du fichier, comme dans -8<- "docs-style-guide.md", ou si le contenu se trouve dans un sous-répertoire, seulement le répertoire et le nom du fichier, comme dans-8<- "style/docs-style-guide.md".
Si vous incluez du contenu externe à partir d'un fichier sur GitHub via une URL, vous doit utiliser l'URL du contenu brut, ou il rendra la page web complète intégrée où que vous l'incluiez.

Utilisation de macros pour inclure le contenu de BeeWare Docs Tools dans le contenu partagé¶

Vous pouvez également inclure du contenu provenant du répertoire de contenu partagé des outils BeeWare Docs en utilisant le plugin Macros MkDocs. Cette méthode est nécessaire si le document contient des directives Jinja qui doivent être exécutées, et ne doit être utilisée que dans cette situation. Elle ne fonctionne pas avec du contenu externe via une URL. Le mécanisme de remplacement des variables Macros fonctionne avec cette méthode.

Il existe des options pour inclure du contenu à l'aide de macros :

Utilisez la syntaxe Jinja include si vous voulez inclure le document sans y apporter d'autres modifications manuelles.
Utilisez la syntaxe Jinja extends si vous avez inclus la syntaxe Jinja block dans le document, ce qui vous permet de remplacer ou d'ajouter des sections spécifiques.

`pyspelling`¶

Nous utilisons le correcteur orthographique pyspelling. Il est exécuté pendant les vérifications lint.

Lorsque pyspelling identifie un mot mal orthographié, dans la plupart des cas, il doit être corrigé dans le contenu de la documentation.

Dans le cas rare où il identifie un mot valide qui n'est pas dans le dictionnaire pyspelling, vous avez deux options :

S'il s'agit d'un mot susceptible d'être réutilisé plusieurs fois, vous devez l'ajouter au document spelling_wordlist dans le répertoire docs, par ordre alphabétique.
S'il s'agit d'un mot qui n'est pas susceptible d'être utilisé à nouveau, vous pouvez le mettre dans une balise <nospell> / </nospell>, et pyspelling l'ignorera en ligne.