ML Community Day is November 9! Join us for updates from TensorFlow, JAX, and more Learn more

Contribuer à la documentation TensorFlow

TensorFlow accepte 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 API -La référence API docs sont générées à partir docstrings dans le code source de tensorflow .
  • Documentation narratives sont -Ce tutoriels , guides et autres écriture qui ne fait pas partie du code tensorflow. Cette documentation est dans le tensorflow / docs dépôt GitHub.
  • Traductions communautaires -Ces sont des guides et des tutoriels traduits par la communauté. Toutes les traductions de la communauté vivent dans le tensorflow / docs repo.

Certains projets tensorflow garder les fichiers sources de documentation près du code dans un dépôt séparé, habituellement dans un docs/ répertoire. Voir le projet CONTRIBUTING.md fichier ou contacter le responsable de contribuer.

Pour participer à la communauté TensorFlow docs :

Référence API

Pour plus de détails, utilisez l' API tensorflow docs guide contributeur . Cela vous montre comment trouver le fichier source et modifier le symbole de docstring . 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. Docstrings soutiennent Markdown et peuvent être (à peu près) visualisés en utilisant tout previewer Markdown .

Versions et branches

Le Site de référence API Version par défaut de la dernière binaire stable ce correspond au package installé avec pip install tensorflow .

Le paquet de tensorflow par défaut est construit à partir de la branche stable rX.x dans la principale tensorflow / tensorflow repo. La documentation de référence est généré à partir des commentaires de code et docstrings dans le code source pour Python , C ++ et Java .

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

Créer des documents d'API

Référence Python

Le tensorflow_docs forfait comprend le générateur pour les documents 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 script:

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

Tensorflow guides et tutoriels sont écrits comme Markdown fichiers et interactifs Jupyter ordinateurs portables. Ordinateurs portables peuvent être exécutés dans votre navigateur en utilisant Google Colaboratory . Les documents narratifs sur tensorflow.org sont construits à partir du tensorflow / docs master branche. Les anciennes versions sont disponibles en GitHub sur les rX.x branches de libération.

Modifications simples

La meilleure façon de faire des mises à jour de documentation directe aux fichiers Markdown est d'utiliser de GitHub éditeur de fichiers basé sur le Web . Parcourir le tensorflow / docs référentiel pour trouver le Markdown qui correspond à peu près à la tensorflow.org structure d'URL. 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.

Fourche le référentiel tensorflow/docs

Sur le tensorflow / docs la page GitHub, 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 votre copie de dépôt avec le dépôt TensorFlow en amont.

Clonez votre dépôt

Télécharger une copie de votre télécommande username d' username / docs repo à votre machine locale. Il s'agit du répertoire de travail dans lequel vous effectuerez les 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 en phase avec tensorflow/docs , ajouter 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

Une fois que vous mettez à jour votre repo de tensorflow/docs , créer une nouvelle branche de la branche maître local:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Apportez des modifications

Modifier les fichiers dans votre éditeur de texte favori et s'il vous plaît suivre le guide de style de 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 à votre repo GitHub à distance (github.com/ username d' username / docs):

git push

Une fois le push terminé, un message peut afficher une URL pour soumettre automatiquement une demande d'extraction au référentiel en amont. Sinon, allez à la tensorflow / docs -pension ou votre pension et GitHub vous invite à créer une demande de traction.

4. Réviser

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 y a une étape d'édition séparée pour la mise à jour tensorflow.org du repo GitHub. En règle générale, les modifications sont regroupées et le site est mis à jour régulièrement.

Cahiers interactifs

Bien qu'il soit possible d'éditer le fichier JSON portable avec de GitHub éditeur de fichiers basé sur le Web , il est pas recommandé car 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 portable hébergé qui le rend facile à la documentation et modifier l' exécution portable. Ordinateurs portables à GitHub sont chargés dans Google Colab en passant le chemin vers l'URL Colab, par exemple, l'ordinateur portable situé à GitHub ici: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
peut être chargé dans Google Colab à l'adresse suivante : https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Il y a un Open in Colab extension Chrome qui effectue cette substitution d'URL lorsque vous naviguez sur un bloc - notes sur GitHub. Ceci est utile lors de l' ouverture d' un ordinateur portable dans votre fourchette de prise en pension, car les boutons du haut lien toujours à la tensorflow Docs master branche.

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 à 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 par défaut avec une préférence opiniâtre pour le flux de travail tensorflow docs Colab. Pour formater un ordinateur portable, installer les outils portables tensorflow docs et exécutez le nbfmt outil:

# 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 tensorflow, ordinateurs portables sans cellules de sortie sont exécutées et testées; ordinateurs portables avec des cellules de sortie enregistrées sont publiées en l' état . nbfmt respecte l'état de bloc - notes et utilise la --remove_outputs option pour supprimer explicitement les cellules de sortie.

Pour créer un nouveau bloc - notes, copier et modifier les tensorflow modèle de bloc - notes docs .

Modifier dans Colab

Dans l'environnement Google Colab, double-cliquez sur les cellules pour modifier les blocs de texte et de code. Cellules de texte utilisent Markdown et devraient suivre le guide de tensorflow de style docs .

Fichiers portables Télécharger de Colab avec Fichier> Télécharger .pynb. Engagez ce fichier à votre repo Git locale et envoyer une demande de tirage.

Pour créer un nouveau bloc - notes, copier et modifier le modèle de bloc - notes 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 référentiel GitHub fork directement depuis Google Colab :

  1. Dans votre fourchue username d' username / docs repo, 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: utiliser l'échange d'URL ou l'Open in Colab extension Chrome.
  4. Modifiez le bloc-notes dans Colab.
  5. Valider les modifications à votre repo de Colab avec Fichier> Enregistrer une copie dans GitHub .... La boîte de dialogue de sauvegarde doit être liée au référentiel et à la branche appropriés. Ajoutez un message de validation significatif.
  6. Après avoir enregistré, accédez à votre pension ou tensorflow / docs repo, GitHub devrait vous inciter à créer une demande de traction.
  7. La demande d'extraction est examinée par les responsables.

Traductions

L'équipe TensorFlow travaille avec la communauté et les fournisseurs pour fournir des traductions pour tensorflow.org. Traductions de cahiers et d' autres contenus techniques sont situés dans le tensorflow / docs-l10n repo GitHub. S'il vous plaît soumettre des demandes de traction à travers le projet tensorflow GitLocalize .

Les documents anglais sont la source de-vérité et les traductions doivent suivre ces guides aussi proches que possible. Cela dit, les traductions sont écrites 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 appropriée pour le lecteur.

Le soutien linguistique est déterminé par un certain nombre de facteurs , y compris, mais sans s'y limiter , place des mesures et de la demande, le soutien communautaire, 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. Prise en charge de nouvelles langues sera annoncé sur le blog de tensorflow ou 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.