Merci d'avoir participé à Google I/O. Regardez toutes les sessions à la demandeRegarder à la demande

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 :

  • Référence de l'API : les documents de référence de l'API sont générés à partir de docstrings dans le code source de TensorFlow .
  • Documentation narrative : il s'agit de didacticiels , de guides et d'autres écrits qui ne font pas partie du code TensorFlow. Cette documentation se trouve dans le référentiel GitHub tensorflow/docs .
  • Traductions communautaires : il s'agit de guides et de didacticiels traduits par la communauté. Toutes les traductions de la communauté résident dans le dépôt tensorflow/docs .

Certains projets TensorFlow conservent les fichiers source de la documentation près du code dans un référentiel séparé, généralement dans un répertoire docs/ . Voir le fichier CONTRIBUTING.md du projet ou contacter le mainteneur pour contribuer.

Pour participer à la communauté de documentation TensorFlow :

Référence API

Pour plus de détails, consultez le guide des contributeurs 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 d'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és à 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, ce qui 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 dépôt principal tensorflow/tensorflow . La documentation de référence est générée à partir des commentaires de code et des docstrings dans le code source pour Python , C++ et Java .

Les versions précédentes de la documentation TensorFlow sont disponibles en tant que branches rX.x dans le référentiel TensorFlow Docs. Ces branches sont ajoutées lorsqu'une nouvelle version est publiée.

Construire des documents d'API

Référence Python

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

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

Pour générer la documentation de référence TensorFlow 2, utilisez le 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 créés à partir de la branche master tensorflow/docs . Les anciennes versions sont disponibles dans GitHub sur les branches de publication rX.x

Changements simples

Le moyen le plus simple de mettre à jour directement 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 référentiel 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 demande d'extraction.

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

Fourchez 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 la mise à jour de la copie de votre référentiel avec le référentiel TensorFlow en amont.

Clonez votre dépôt

Téléchargez une copie de votre nom d' username distant / référentiel 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 référentiel en amont pour rester à jour (facultatif)

Pour synchroniser votre référentiel local 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)

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éer une nouvelle branche

Après avoir mis à jour votre référentiel à partir de 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éer une pull request

Téléchargez votre branche locale sur votre référentiel GitHub distant (github.com/ 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. Si ce n'est pas le cas, accédez au référentiel tensorflow/docs ou à votre propre référentiel et GitHub vous invitera à créer une demande d'extraction.

4. Examen

Les mainteneurs et autres contributeurs examineront votre pull request. Veuillez participer à la discussion et apporter les modifications demandées. Une fois votre demande d'extraction approuvée, elle sera fusionnée dans le référentiel de documents TensorFlow en amont.

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

Carnets interactifs

Bien qu'il soit possible de modifier le fichier JSON du bloc-notes avec l' éditeur de fichiers Web de GitHub, cela n'est pas recommandé car un JSON malformé peut corrompre le fichier. Assurez-vous de tester le bloc-notes avant de soumettre une demande d'extraction.

Google Colaboratory est un environnement de bloc-notes hébergé qui facilite la modification et l'exécution de la documentation des blocs-notes. Les blocs-notes dans GitHub sont chargés dans Google Colab en transmettant le chemin d'accès à l'URL Colab, par exemple, le bloc-notes 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 bloc-notes dans votre repo fork, car les boutons du haut sont toujours liés à la branche master de TensorFlow Docs.

Formatage du bloc-notes

Un outil de formatage de bloc-notes rend les différences de source de bloc-notes Jupyter cohérentes et plus faciles à examiner. É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 opiniâtres avec une préférence pour le flux de travail TensorFlow docs Colab. Pour formater un bloc-notes, installez les outils de bloc-notes de documentation TensorFlow 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 de documentation TensorFlow, les blocs-notes 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 bloc-notes 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 TensorFlow docs .

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 des documents TensorFlow .

Téléchargez des fichiers de bloc-notes depuis Colab avec Fichier > Télécharger .pynb . Validez ce fichier dans votre référentiel Git local et envoyez une demande d'extraction.

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

Flux de travail Colab-GitHub

Au lieu de télécharger un fichier de bloc-notes et d'utiliser un flux de travail Git local, vous pouvez modifier et mettre à jour votre référentiel GitHub dérivé directement depuis Google Colab :

  1. Dans votre dépôt de nom d' username /docs dérivé, utilisez l'interface utilisateur Web GitHub pour créer une nouvelle branche .
  2. Accédez au fichier de bloc-notes à modifier.
  3. Ouvrez le bloc-notes dans Google Colab : utilisez l'échange d'URL ou l'extension Ouvrir dans Colab Chrome.
  4. Modifiez le bloc-notes dans Colab.
  5. Validez les modifications apportées à votre référentiel à partir de Colab avec File > Save a copy in GitHub... . La boîte de dialogue de sauvegarde doit être liée au dépôt et à la branche appropriés. Ajoutez un message de validation significatif.
  6. Après avoir enregistré, accédez à votre référentiel ou au référentiel tensorflow/docs , GitHub devrait vous inviter à créer une demande d'extraction.
  7. La pull request est examinée par les mainteneurs.

Traductions

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

Les documents en anglais sont la source de vérité et les traductions doivent suivre ces guides aussi étroitement que possible. Cela dit, les traductions sont écrites pour les communautés qu'elles desservent. Si la terminologie, la formulation, le style ou le ton anglais ne se traduisent pas dans une autre langue, veuillez utiliser une traduction appropriée pour le lecteur.

Le support linguistique est déterminé par un certain nombre de facteurs, y compris, mais sans s'y limiter, les mesures et la demande du site, le support de la communauté, la maîtrise de l'anglais , la préférence du public et d'autres indicateurs. Étant donné que chaque langue prise en charge entraîne un coût, les langues non gérées 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.