Contribuer à la documentation TensorFlow

TensorFlow accueille les contributions à la documentation : si vous améliorez la documentation, vous améliorez la bibliothèque TensorFlow elle-même. La documentation sur tensorflow.org appartient aux catégories suivantes :

Certains projets TensorFlow conservent les fichiers sources de la documentation à proximité du code dans un référentiel distinct, généralement dans un répertoire docs/ . Consultez le fichier CONTRIBUTING.md du projet ou contactez le responsable pour contribuer.

Pour participer à la communauté de documents TensorFlow :

Référence API

Pour plus de détails, utilisez le guide du contributeur de la documentation de l'API TensorFlow . Cela vous montre comment trouver le fichier source et modifier la docstring du symbole. De nombreuses pages de référence API sur tensorflow.org incluent un lien vers le fichier source où le symbole est défini. Les Docstrings prennent en charge Markdown et peuvent être (approximativement) prévisualisées à l'aide de n'importe quel outil de prévisualisation Markdown .

Versions et branches

La version de référence de l'API du site utilise par défaut le dernier binaire stable. Cela correspond au package installé avec pip install tensorflow .

Le package TensorFlow par défaut est construit à partir de la branche stable rX.x dans le référentiel tensorflow/tensorflow principal. La documentation de référence est générée à partir de commentaires de code et de docstrings dans le code source de Python , C++ et Java .

Les versions précédentes de la documentation TensorFlow sont disponibles sous forme de branches rX.x dans le référentiel TensorFlow Docs. Ces branches sont ajoutées lors de la sortie d'une nouvelle version.

Créer des documents sur l'API

Référence Python

Le package tensorflow_docs inclut le générateur pour la documentation de référence de l'API Python . Pour installer :

pip install git+https://github.com/tensorflow/docs

Pour générer les documents de référence TensorFlow 2, utilisez le script tensorflow/tools/docs/generate2.py :

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

Documentation narrative

Les guides et didacticiels TensorFlow sont écrits sous forme de fichiers Markdown et de blocs-notes Jupyter interactifs. Les blocs-notes peuvent être exécutés dans votre navigateur à l'aide de Google Colaboratory . Les documents narratifs sur tensorflow.org sont construits à partir de la branche master tensorflow/docs . Les anciennes versions sont disponibles dans GitHub sur les branches de version rX.x

Des changements simples

Le moyen le plus simple d'effectuer des mises à jour simples de la documentation des fichiers Markdown consiste à utiliser l'éditeur de fichiers Web de GitHub. Parcourez le référentiel tensorflow/docs pour trouver le Markdown qui correspond à peu près à la structure d'URL tensorflow.org . Dans le coin supérieur droit de la vue du fichier, cliquez sur l'icône en forme de crayon pour ouvrir l'éditeur de fichiers. Modifiez le fichier, puis soumettez une nouvelle demande d'extraction.

Configurer un dépôt Git local

Pour les modifications multi-fichiers ou les mises à jour plus complexes, il est préférable d'utiliser un workflow Git local pour créer une pull request.

Les étapes Git suivantes ne sont requises que la première fois que vous configurez un projet local.

Forkez le dépôt tensorflow/docs

Sur la page GitHub tensorflow/docs , cliquez sur le bouton Fork pour créer votre propre copie de dépôt sous votre compte GitHub. Une fois forké, vous êtes responsable de maintenir votre copie de dépôt à jour avec le dépôt TensorFlow en amont.

Clonez votre dépôt

Téléchargez une copie de votre dépôt username distant /docs sur votre ordinateur local. Il s'agit du répertoire de travail dans lequel vous apporterez des modifications : 

git clone git@github.com:username/docs
cd ./docs

Ajouter un dépôt en amont pour rester à jour (facultatif)

Pour garder votre référentiel local synchronisé avec tensorflow/docs , ajoutez une télécommande en amont pour télécharger les dernières modifications.

Ajouter une télécommande :

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

Pour mettre à jour : 

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

Flux de travail GitHub

1. Créez une nouvelle branche

Après avoir mis à jour votre dépôt depuis tensorflow/docs , créez une nouvelle branche à partir de la branche principale locale : 

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Apportez des modifications

Modifiez les fichiers dans votre éditeur préféré et suivez le guide de style de la documentation TensorFlow .

Validez votre modification de fichier :

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

Ajoutez plus de commits, si nécessaire.

3. Créez une demande de tirage

Téléchargez votre branche locale sur votre dépôt GitHub distant ( username /docs) :

git push

Une fois le push terminé, un message peut afficher une URL pour soumettre automatiquement une demande d'extraction au dépôt en amont. Sinon, accédez au dépôt tensorflow/docs (ou à votre propre dépôt) et GitHub vous demandera de créer une pull request.

4. Révision

Les responsables et autres contributeurs examineront votre demande d'extraction. Veuillez participer à la discussion et apporter les modifications demandées. Une fois votre demande d'extraction approuvée, elle sera fusionnée dans le dépôt de documents TensorFlow en amont.

Il existe une étape de publication distincte pour mettre à jour tensorflow.org à partir du dépôt GitHub. En règle générale, les modifications sont regroupées et le site est mis à jour à une cadence régulière.

Cahiers interactifs

Bien qu'il soit possible de modifier le fichier JSON du notebook avec l'éditeur de fichiers Web de GitHub, cela n'est pas recommandé car un JSON mal formé peut corrompre le fichier. Assurez-vous de tester le notebook avant de soumettre une pull request.

Google Colaboratory est un environnement de bloc-notes hébergé qui facilite la modification et l'exécution de la documentation du bloc-notes. Les notebooks dans GitHub sont chargés dans Google Colab en transmettant le chemin d'accès à l'URL de Colab, par exemple, le notebook situé dans GitHub ici : https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
peut être chargé dans Google Colab à cette URL : https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Il existe une extension Open in Colab Chrome qui effectue cette substitution d'URL lors de la navigation dans un bloc-notes sur GitHub. Ceci est utile lors de l'ouverture d'un notebook dans votre fork de dépôt, car les boutons du haut sont toujours liés à la branche master TensorFlow Docs.

Formatage du bloc-notes

Un outil de formatage de notebook rend les différences sources des notebooks Jupyter cohérentes et plus faciles à consulter. Étant donné que les environnements de création de blocs-notes diffèrent en ce qui concerne la sortie des fichiers, l'indentation, les métadonnées et d'autres champs non spécifiés ; nbfmt utilise des valeurs par défaut avisées avec une préférence pour le workflow Colab de TensorFlow docs. Pour formater un notebook, installez les outils de notebook TensorFlow docs et exécutez l'outil nbfmt :

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

Pour les projets TensorFlow Docs, les notebooks sans cellules de sortie sont exécutés et testés ; les blocs-notes avec des cellules de sortie enregistrées sont publiés tels quels. nbfmt respecte l'état du notebook et utilise l'option --remove_outputs pour supprimer explicitement les cellules de sortie.

Pour créer un bloc-notes, copiez et modifiez le modèle de bloc-notes de documents TensorFlow .

Modifier dans Colab

Dans l'environnement Google Colab, double-cliquez sur les cellules pour modifier les blocs de texte et de code. Les cellules de texte utilisent Markdown et doivent suivre le guide de style de la documentation TensorFlow .

Téléchargez les fichiers du notebook depuis Colab avec File > Download .pynb . Validez ce fichier dans votre dépôt Git local et envoyez une pull request.

Pour créer un nouveau notebook, copiez et modifiez le modèle de notebook TensorFlow .

Flux de travail Colab-GitHub

Au lieu de télécharger un fichier notebook et d'utiliser un workflow Git local, vous pouvez modifier et mettre à jour votre dépôt GitHub forké directement depuis Google Colab :

  1. Dans votre dépôt username /docs forké, utilisez l'interface utilisateur Web GitHub pour créer une nouvelle branche .
  2. Accédez au fichier du bloc-notes à modifier.
  3. Ouvrez le notebook dans Google Colab : utilisez l'échange d'URL ou l'extension Chrome Open in Colab .
  4. Modifiez le bloc-notes dans Colab.
  5. Validez les modifications apportées à votre dépôt depuis Colab avec Fichier > Enregistrer une copie dans GitHub... . La boîte de dialogue de sauvegarde doit créer un lien vers le dépôt et la branche appropriés. Ajoutez un message de validation significatif.
  6. Après l'enregistrement, accédez à votre dépôt ou au dépôt tensorflow/docs , GitHub devrait vous inviter à créer une pull request.
  7. La pull request est examinée par les responsables.

Traductions

L'équipe TensorFlow travaille avec la communauté et les fournisseurs pour fournir des traductions pour tensorflow.org. Les traductions des notebooks et autres contenus techniques se trouvent dans le dépôt GitHub tensorflow/docs-l10n . Veuillez soumettre des demandes d'extraction via le projet TensorFlow GitLocalize .

Les documents anglais sont la source de la vérité et les traductions doivent suivre ces guides aussi fidèlement que possible. Cela dit, les traductions sont rédigées pour les communautés qu’elles servent. Si la terminologie, la formulation, le style ou le ton anglais ne se traduisent pas dans une autre langue, veuillez utiliser une traduction adaptée au lecteur.

Le support linguistique est déterminé par un certain nombre de facteurs, notamment, mais sans s'y limiter, les mesures et la demande du site, le soutien de la communauté, la maîtrise de l'anglais , les préférences du public et d'autres indicateurs. Étant donné que chaque langue prise en charge entraîne un coût, les langues non maintenues sont supprimées. La prise en charge de nouvelles langues sera annoncée sur le blog TensorFlow ou sur Twitter .

Si votre langue préférée n'est pas prise en charge, vous pouvez maintenir un fork communautaire pour les contributeurs open source. Ceux-ci ne sont pas publiés sur tensorflow.org.