Guide de style de la documentation TensorFlow

Meilleures pratiques

• Concentrez-vous sur l’intention et le public de l’utilisateur.
• Utilisez des mots de tous les jours et faites des phrases courtes.
• Utilisez une construction de phrase, une formulation et une majuscule cohérentes.
• Utilisez des titres et des listes pour faciliter la numérisation de vos documents.
• Le guide de style Google Developer Docs est utile.

Réduction

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

Écrire sur le code

Mentions en ligne du code

Mettez `backticks` autour des symboles suivants lorsqu'ils sont utilisés dans le texte :

• Noms des arguments : `input` , `x` , `tensor`
• Noms de tenseurs renvoyés : `output` , `idx` , `out`
• Types de données : `int32` , `float` , `uint8`
• Autres noms d'opérations référencés dans le texte : `list_diff()` , `shuffle()`
• Noms de classe : `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 backticks pour ouvrir et fermer un bloc de code. Eventuellement, spécifiez le langage de programmation après le premier groupe de backticks, par exemple :

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

Liens dans Markdown et notebooks

Liens entre fichiers dans un référentiel

Utilisez des liens relatifs entre les fichiers dans un seul référentiel GitHub. Incluez l'extension du fichier.

Par exemple, ce fichier que vous lisez provient du référentiel https://github.com/tensorflow/docs . Par conséquent, il peut utiliser des chemins relatifs pour créer des liens vers d’autres fichiers dans le même référentiel, comme ceci :

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

C'est l'approche préférée car de cette façon, les liens sur tensorflow.org , GitHub et Colab fonctionnent tous. 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 référentiel actuel, utilisez des liens Markdown standard avec l'URI complet. Préférez créer un lien vers l'URI tensorflow.org s'il 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 commençant à la racine GitHub.

Lors de la création d'un lien depuis tensorflow.org , incluez un `` sur 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 :

• Utilisez : <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
• Non : <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Images

Les conseils de la section précédente concernent les liens vers des pages. Les images sont traitées différemment.

En règle générale, vous ne devez pas archiver les images, mais plutôt ajouter l' équipe TensorFlow-Docs à votre PR et leur demander d'héberger les images sur tensorflow.org . Cela permet de réduire la taille de votre référentiel.

Si vous soumettez des images à votre référentiel, notez que certains systèmes ne gèrent pas les chemins relatifs vers les images. Préférez utiliser une URL complète pointant vers l'emplacement éventuel 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 de l'API d'un symbole, entourez le chemin du symbole entre des backticks :

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

Les chemins complets sont légèrement préférés, sauf pour les chemins longs. Les chemins peuvent être abrégés en supprimant les principaux composants du chemin. Les chemins partiels seront convertis en liens si :

• Il y en a au moins un . sur le chemin, et
• Le chemin partiel est unique au sein du projet.

Les chemins d'API sont liés pour chaque projet avec une API Python publiée sur tensorflow.org . Vous pouvez facilement créer un lien vers plusieurs sous-projets à partir d'un seul fichier en enveloppant les noms d'API avec des backticks. Par exemple:

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

Pour les symboles avec plusieurs alias de chemin, il existe une légère préférence pour le chemin qui correspond à la page API sur tensorflow.org . Tous les alias seront redirigés vers la bonne page.

Mathématiques en Markdown

Vous pouvez utiliser MathJax dans TensorFlow lors de la modification de fichiers Markdown, mais notez 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 peu familiers.
• 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 \]

Enveloppez 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 mathématiques en ligne, mais la forme $ est parfois plus lisible.

Style de prose

Si vous envisagez d'écrire ou de modifier des parties importantes de la documentation narrative, veuillez lire le Guide de style de la documentation du développeur Google .

Principes de bon style

• Vérifiez l’orthographe et la grammaire de vos contributions. La plupart des éditeurs incluent un correcteur orthographique ou disposent d'un plugin de vérification orthographique. Vous pouvez également coller votre texte dans un Google Doc ou un autre logiciel de documentation pour une vérification orthographique et grammaticale plus solide.
• Utilisez une voix décontractée et amicale. Écrivez la documentation TensorFlow comme une conversation, comme si vous parliez à une autre personne en tête-à-tête. Utilisez un ton de soutien dans l’article.

• Évitez les avertissements, les opinions et les jugements de valeur. Des mots comme « facilement », « juste » et « simple » sont chargés d'hypothèses. Quelque chose peut vous sembler facile, mais être difficile pour une autre personne. Essayez de les éviter autant que possible.
• Utilisez des phrases simples et précises, sans jargon compliqué. Les phrases composées, les chaînes de clauses et les expressions idiomatiques spécifiques à un lieu peuvent rendre le texte difficile à comprendre et à traduire. Si une phrase peut être divisée en deux, elle le devrait probablement. Évitez les points-virgules. Utilisez des listes à puces le cas échéant.
• Fournissez le contexte. N'utilisez pas d'abréviations sans les expliquer. Ne mentionnez pas les projets non TensorFlow sans créer de lien vers eux. Expliquez pourquoi le code est écrit tel quel.

Guide d'utilisation

Opérations

Dans les fichiers markdown, utilisez # ⇒ au lieu d'un seul signe égal lorsque vous souhaitez afficher ce que renvoie une opération.

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

Dans les cahiers, affichez le résultat au lieu d'ajouter un commentaire (Si la dernière expression d'une cellule du cahier n'est pas affectée à une variable, elle est automatiquement affichée.)

Dans les documents de référence de l'API, préférez utiliser doctest pour afficher les résultats.

Tenseurs

Lorsque vous parlez d'un tenseur en général, ne mettez pas le mot tenseur en majuscule. Lorsque vous parlez de l'objet spécifique fourni ou renvoyé par une opération, vous devez alors mettre le mot Tensor en majuscule et ajouter des guillemets autour de lui, car vous parlez d'un objet Tensor .

N'utilisez pas le mot Tensors (pluriel) pour décrire plusieurs objets Tensor sauf si vous parlez vraiment d'un objet Tensors . Au lieu de cela, dites "une liste (ou une collection) d'objets Tensor ".

Utilisez le mot forme pour détailler les axes d'un tenseur et affichez la forme entre crochets avec des guillemets. 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 ci-dessus, préférez "axis" ou "index" à "dimension" lorsque vous parlez des éléments de la forme d'un Tensor . Sinon, il est facile de confondre « dimension » avec la dimension d'un espace vectoriel. Un « vecteur tridimensionnel » a un seul axe de longueur 3.