Cette page a été traduite par l'API Cloud Translation.

Guide de style de la documentation TensorFlow

meilleures pratiques

Concentrez-vous sur l'intention de l'utilisateur et sur le public cible.
Utilisez un vocabulaire courant et faites des phrases courtes.
Utilisez une construction de phrases, un vocabulaire et une ponctuation cohérents.
Utilisez des titres et des listes pour faciliter la lecture de vos documents.
Le guide de style de Google Developer Docs est utile.

Réduction

À quelques exceptions près, TensorFlow utilise une syntaxe Markdown similaire à celle de GitHub Flavored Markdown (GFM). Cette section explique les différences entre la syntaxe Markdown de GFM et celle utilisée pour la documentation de TensorFlow.

Écrivez sur le code

Mentions de code en ligne

Encadrez les symboles suivants par `backticks` lorsqu'ils sont utilisés dans un texte :

Noms des arguments : `input` , `x` , `tensor`
Noms des tenseurs renvoyés : `output` , `idx` , `out`
Types de données : `int32` , `float` , `uint8`
Autres noms d'opérations mentionnés dans le texte : `list_diff()` , `shuffle()`
Noms de classes : `tf.Tensor` , `Strategy`
Nom du fichier : `image_ops.py` , `/path_to_dir/file_name`
Expressions ou conditions mathématiques : `-1-input.dims() <= dim <= input.dims()`

blocs de code

Utilisez trois accents graves (```) pour ouvrir et fermer un bloc de code. Vous pouvez également spécifier le langage de programmation après le premier groupe d'accents graves, par exemple :


```python
# some python code here
```

Liens dans Markdown et carnets

Liens entre les fichiers d'un dépôt

Utilisez des liens relatifs entre les fichiers d'un même dépôt GitHub. Incluez l'extension du fichier.

Par exemple, le fichier que vous êtes en train de lire provient du dépôt https://github.com/tensorflow/docs . Il peut donc utiliser des chemins relatifs pour pointer vers d'autres fichiers du même dépôt, comme ceci :

[Basics](../../guide/basics.ipynb) produit Basics .

Cette méthode est préférable car elle permet aux liens sur tensorflow.org , GitHub et Colab de fonctionner. De plus, le lecteur reste sur le même site lorsqu'il clique sur un lien.

Liens externes

Pour les liens vers des fichiers qui ne se trouvent pas dans le dépôt actuel, utilisez les liens Markdown standard avec l'URI complète. Privilégiez l'URI tensorflow.org si elle est disponible.

Pour créer un lien vers le code source, utilisez un lien commençant par https://www.github.com/tensorflow/tensorflow/blob/master/ , suivi du nom du fichier à partir de la racine GitHub.

Lors de la création d'un lien depuis tensorflow.org , incluez un `` dans le lien Markdown afin que le symbole « lien externe » s'affiche.

[GitHub](https://github.com/tensorflow/docs) produit GitHub

N’incluez pas les paramètres de requête URI dans le lien :

Utilisation : https://www.tensorflow.org/guide/data
Remarque : https://www.tensorflow.org/guide/data?hl=en

Images

Les conseils de la section précédente concernent les liens vers des pages. Le traitement des images est différent.

En règle générale, il est déconseillé d'inclure les images dans votre dépôt. Il est préférable d'ajouter l' équipe TensorFlow-Docs à votre demande de fusion et de leur demander d'héberger les images sur tensorflow.org . Cela permet de réduire la taille de votre dépôt.

Si vous soumettez des images à votre dépôt, veuillez noter que certains systèmes ne prennent pas en charge les chemins relatifs vers les images. Il est préférable d'utiliser une URL complète pointant vers l'emplacement final de l'image sur tensorflow.org .

Liens vers la documentation de l'API

Les liens API sont convertis lors de la publication du site. Pour créer un lien vers la page de référence API d'un symbole, placez le chemin du symbole entre guillemets inversés (```).

`tf.data.Dataset` produit tf.data.Dataset

Les chemins complets sont légèrement privilégiés, sauf pour les chemins longs. Les chemins peuvent être abrégés en supprimant leurs premiers composants. Les chemins partiels seront convertis en liens si :

Il y a au moins un . dans le chemin, et
Ce chemin partiel est unique au sein du projet.

Les chemins d'accès aux API sont disponibles pour chaque projet disposant d'une API Python publiée sur tensorflow.org . Vous pouvez facilement créer des liens vers plusieurs sous-projets à partir d'un seul fichier en encadrant les noms d'API par des guillemets inversés (backticks). Par exemple :

`tf.metrics` , `tf_agents.metrics` , `text.metrics` produit : tf.metrics , tf_agents.metrics , text.metrics .

Pour les symboles possédant plusieurs alias de chemin, la préférence va légèrement à celui correspondant à la page API sur tensorflow.org . Tous les alias redirigeront vers la page appropriée.

Mathématiques en Markdown

Vous pouvez utiliser MathJax dans TensorFlow lors de l'édition de fichiers Markdown, mais veuillez noter ce qui suit :

MathJax s'affiche correctement sur tensorflow.org .
MathJax ne s'affiche pas correctement sur GitHub.
Cette notation peut être rebutante pour les développeurs non familiarisés avec elle.
Par souci de cohérence, tensorflow.org suit les mêmes règles que Jupyter/Colab.

Utilisez $$ autour d'un bloc de MathJax :

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Encadrez les expressions MathJax en ligne avec $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Voici un exemple d'expression MathJax en ligne : $ 2 \times 2 = 4 $

Les délimiteurs \$ ... \$ fonctionnent également pour les formules mathématiques en ligne, mais la forme $ est parfois plus lisible.

Style de prose

Si vous devez rédiger ou modifier des parties importantes de la documentation narrative, veuillez lire le Guide de style de la documentation pour développeurs de Google .

Principes du bon style

Vérifiez l'orthographe et la grammaire de vos contributions. La plupart des logiciels de traitement de texte intègrent un correcteur orthographique ou proposent un module complémentaire. Vous pouvez également coller votre texte dans un document Google Docs ou un autre logiciel de traitement de texte pour une vérification orthographique et grammaticale plus approfondie.
Adoptez un ton décontracté et amical. Rédigez la documentation TensorFlow comme une conversation, comme si vous vous adressiez directement à une autre personne. Utilisez un ton encourageant dans l'article.

Évitez les formules de politesse, les opinions et les jugements de valeur. Des mots comme « facilement », « juste » et « simple » sont empreints de présomptions. Ce qui vous paraît facile peut être difficile pour une autre personne. Essayez de les éviter autant que possible.
Utilisez des phrases simples et concises, sans jargon complexe. Les phrases composées, les enchaînements de propositions et les expressions idiomatiques spécifiques à un lieu peuvent rendre un texte difficile à comprendre et à traduire. Si une phrase peut être scindée en deux, il est préférable de le faire. Évitez les points-virgules. Utilisez des listes à puces lorsque cela est pertinent.
Fournissez du contexte. N'utilisez pas d'abréviations sans les expliquer. Ne mentionnez pas de projets autres que TensorFlow sans les référencer. Expliquez pourquoi le code est écrit de cette manière.

Guide d'utilisation

Opérations

Dans les fichiers Markdown, utilisez # ⇒ au lieu d'un simple signe égal lorsque vous souhaitez afficher la valeur renvoyée par une opération.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

Dans les blocs-notes, afficher le résultat au lieu d'ajouter un commentaire (si la dernière expression d'une cellule de bloc-notes n'est pas affectée à une variable, elle est automatiquement affichée).

Dans la documentation de référence de l'API, il est préférable d'utiliser doctest pour afficher les résultats.

Tenseurs

Lorsqu'on parle d'un tenseur en général, on n'écrit pas « tensor » avec une majuscule. En revanche, lorsqu'on parle de l'objet spécifique fourni à une opération ou renvoyé par celle-ci, on écrit « tensor » avec une majuscule et on l'entoure d'accents graves, car il s'agit d'un objet Tensor .

N’utilisez pas le terme « Tenseurs » (au pluriel) pour désigner plusieurs objets Tensor , sauf si vous parlez réellement d’un seul objet Tensors . Dites plutôt « une liste (ou collection) d’objets Tensor ».

Utilisez le terme « forme » pour décrire les axes d'un tenseur et indiquez la forme entre crochets avec des guillemets obliques. Par exemple :


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Comme indiqué précédemment, il est préférable d'utiliser « axe » ou « indice » plutôt que « dimension » pour décrire les éléments d'un Tensor . Autrement, il est facile de confondre « dimension » avec la dimension d'un espace vectoriel. Un vecteur tridimensionnel possède un seul axe de longueur 3.