Tragen Sie zur TensorFlow-Dokumentation bei

TensorFlow begrüßt Dokumentationsbeiträge. Wenn Sie die Dokumentation verbessern, verbessern Sie die TensorFlow-Bibliothek selbst. Die Dokumentation auf tensorflow.org fällt in folgende Kategorien:

Einige TensorFlow-Projekte speichern Dokumentationsquelldateien in der Nähe des Codes in einem separaten Repository, normalerweise in einem docs/ . Sehen Sie sich die Datei CONTRIBUTING.md des Projekts an oder wenden Sie sich an den Betreuer, um einen Beitrag zu leisten.

So nehmen Sie an der TensorFlow-Community teil:

API-Referenz

Zur Aktualisierung Referenzdokumentation, finden Sie die Quelldatei und bearbeiten das Symbol docstring . Viele API-Referenzseiten auf tensorflow.org enthalten einen Link zur Quelldatei, in der das Symbol definiert ist. Docstrings unterstützen Markdown und können mit jedem Markdown- Previewer (ungefähr) in der Vorschau angezeigt werden.

Informationen zur Qualität der Referenzdokumentation und zur Einbindung in Doc-Sprints und die Community finden Sie in den Hinweisen zu TensorFlow 2 API Docs .

Versionen und Zweige

Die API-Referenzversion der Site verwendet standardmäßig die neueste stabile Binärdatei. Dies entspricht dem Paket, das mit pip install tensorflow .

Das Standard-TensorFlow-Paket wird aus dem stabilen Zweig rX.x im Haupt- Tensorflow / Tensorflow- Repo erstellt. Die Referenzdokumentation wird aus Codekommentaren und Dokumentzeichenfolgen im Quellcode für Python , C ++ und Java generiert.

Frühere Versionen der TensorFlow-Dokumentation sind als rX.x-Zweige im TensorFlow Docs-Repository verfügbar. Diese Zweige werden hinzugefügt, wenn eine neue Version veröffentlicht wird.

Erstellen Sie API-Dokumente

Python-Referenz

Das Paket tensorflow_docs enthält den Generator für die Python-API-Referenzdokumente . Installieren:

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

Verwenden tensorflow/tools/docs/generate2.py zum Generieren der TensorFlow 2-Referenzdokumente das 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

Narrative Dokumentation

TensorFlow- Anleitungen und -Tutorials werden als Markdown- Dateien und interaktive Jupyter- Notizbücher geschrieben. Notizbücher können mit Google Colaboratory in Ihrem Browser ausgeführt werden. Die Erzählung docs auf tensorflow.org werden vom eingebauten tensorflow / docs master - Zweig. Ältere Versionen sind in GitHub in den Release-Zweigen von rX.x verfügbar.

Einfache Änderungen

Der einfachste Weg, um Dokumentationsaktualisierungen an Markdown-Dateien vorzunehmen, ist die Verwendung des webbasierten Datei-Editors von GitHub. Durchsuchen Sie das Tensorflow / Docs- Repository, um den Markdown zu finden, der in etwa der URL-Struktur von tensorflow.org entspricht. Klicken Sie in der oberen rechten Ecke der Dateiansicht auf das Stiftsymbol um den Datei-Editor zu öffnen. Bearbeiten Sie die Datei und senden Sie eine neue Pull-Anfrage.

Richten Sie ein lokales Git-Repo ein

Für Bearbeitungen mit mehreren Dateien oder komplexere Updates ist es besser, einen lokalen Git-Workflow zu verwenden, um eine Pull-Anforderung zu erstellen.

Die folgenden Git-Schritte sind nur erforderlich, wenn Sie zum ersten Mal ein lokales Projekt einrichten.

Fork das Tensorflow / Docs Repo

Klicken Sie auf der GitHub-Seite tensorflow / docs auf die Schaltfläche Fork um deine eigene Repo-Kopie unter deinem GitHub-Konto zu erstellen. Nach dem Verzweigen sind Sie dafür verantwortlich, Ihre Repo-Kopie mit dem vorgelagerten TensorFlow-Repo auf dem neuesten Stand zu halten.

Klonen Sie Ihr Repo

Laden Sie eine Kopie Ihres Remote- username / Docs-Repos auf Ihren lokalen Computer herunter. Dies ist das Arbeitsverzeichnis, in dem Sie Änderungen vornehmen werden:

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

Fügen Sie ein Upstream-Repo hinzu, um auf dem neuesten Stand zu bleiben (optional)

Um Ihr lokales Repository mit tensorflow/docs synchron zu tensorflow/docs , fügen Sie eine Upstream- Fernbedienung hinzu, um die neuesten Änderungen herunterzuladen.

Fügen Sie eine Fernbedienung hinzu:

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)

Aktualisieren:

git checkout master
git pull upstream master

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

GitHub-Workflow

1. Erstellen Sie einen neuen Zweig

Nachdem Sie Ihre Repo aus aktualisieren tensorflow/docs , eine Niederlassung von dem lokalen Master - Zweig erstellen:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Nehmen Sie Änderungen vor

Bearbeiten Sie die Dateien in Ihrem bevorzugten Editor und befolgen Sie die Stilrichtlinien für die TensorFlow-Dokumentation .

Übernehmen Sie Ihre Dateiänderung:

# 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."

Fügen Sie nach Bedarf weitere Commits hinzu.

3. Erstellen Sie eine Pull-Anfrage

Laden Sie Ihre lokale Niederlassung zur Remote - GitHub Repo (github.com/ username / docs):

git push

Nach Abschluss des Pushs wird in einer Nachricht möglicherweise eine URL angezeigt, über die automatisch eine Pull-Anforderung an das Upstream-Repo gesendet wird. Wenn nicht, gehen Sie zum Tensorflow / Docs- Repo - oder zu Ihrem eigenen Repo - und GitHub fordert Sie auf, eine Pull-Anfrage zu erstellen.

4. Überprüfen

Betreuer und andere Mitwirkende überprüfen Ihre Pull-Anfrage. Bitte nehmen Sie an der Diskussion teil und nehmen Sie die gewünschten Änderungen vor. Wenn Ihre Pull-Anfrage genehmigt wurde, wird sie in das vorgelagerte TensorFlow-Dokument-Repo eingefügt.

Es gibt einen separaten Veröffentlichungsschritt zum Aktualisieren von tensorflow.org aus dem GitHub-Repo. In der Regel werden Änderungen zusammengefasst und die Site wird regelmäßig aktualisiert.

Interaktive Notizbücher

Es ist zwar möglich, die Notebook-JSON-Datei mit dem webbasierten Datei-Editor von GitHub zu bearbeiten, dies wird jedoch nicht empfohlen, da fehlerhaftes JSON die Datei beschädigen kann. Stellen Sie sicher, dass Sie das Notebook testen, bevor Sie eine Pull-Anfrage senden.

Google Colaboratory ist eine gehostete Notebook-Umgebung, mit der Sie die Notebook-Dokumentation einfach bearbeiten und ausführen können. Notizbücher in GitHub werden in Google Colab geladen, indem der Pfad zur Colab-URL übergeben wird, z. B. das Notizbuch in GitHub hier: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
kann unter folgender URL in Google Colab geladen werden: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Es gibt eine Open in Colab Chrome-Erweiterung, die diese URL-Ersetzung beim Durchsuchen eines Notizbuchs auf GitHub durchführt. Dies ist nützlich , wenn ein Notebook in Ihrer Repo - Gabel zu öffnen, da die oberen Knöpfe immer auf den TensorFlow Text & Tabellen verknüpfen master - Zweig.

Notebook-Formatierung

Ein Notebook-Formatierungswerkzeug macht Jupyter-Notebook-Quellendifferenzen konsistent und einfacher zu überprüfen. Da sich die Authoring-Umgebungen für Notebooks in Bezug auf Dateiausgabe, Einrückung, Metadaten und andere nicht angegebene Felder unterscheiden. nbfmt verwendet nbfmt mit nbfmt wobei der Colab-Workflow für TensorFlow-Dokumente bevorzugt wird. Installieren Sie zum Formatieren eines Notizbuchs die Notizbuch-Tools von TensorFlow docs und führen Sie das Tool 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 [...]

Bei TensorFlow-Dokumentprojekten werden Notizbücher ohne Ausgabezellen ausgeführt und getestet. Notebooks mit gespeicherten Ausgabezellen werden unverändert veröffentlicht. nbfmt respektiert den Notizbuchstatus und verwendet die Option --remove_outputs , um Ausgabezellen explizit zu entfernen.

Kopieren und bearbeiten Sie zum Erstellen eines neuen Notizbuchs die Notizbuchvorlage für TensorFlow-Dokumente .

In Colab bearbeiten

Doppelklicken Sie in der Google Colab-Umgebung auf Zellen, um Text- und Codeblöcke zu bearbeiten. Textzellen verwenden Markdown und sollten dem Styleguide für TensorFlow-Dokumente folgen.

Laden Sie Notebook-Dateien von Colab mit Datei> .pynb herunterladen herunter . Übernehmen Sie diese Datei in Ihr lokales Git-Repo und senden Sie eine Pull-Anfrage.

Kopieren und bearbeiten Sie die TensorFlow-Notizbuchvorlage, um ein neues Notizbuch zu erstellen.

Colab-GitHub-Workflow

Anstatt eine Notebook-Datei herunterzuladen und einen lokalen Git-Workflow zu verwenden, können Sie Ihr gespaltenes GitHub-Repo direkt in Google Colab bearbeiten und aktualisieren:

  1. Verwenden Sie in Ihrem gespaltenen username / Dokument-Repo die GitHub-Web-Benutzeroberfläche, um einen neuen Zweig zu erstellen .
  2. Navigieren Sie zu der zu bearbeitenden Notizbuchdatei.
  3. Öffnen Sie das Notizbuch in Google Colab: Verwenden Sie den URL-Swap oder die Erweiterung In Colab Chrome öffnen .
  4. Bearbeiten Sie das Notizbuch in Colab.
  5. Übernehmen Sie die Änderungen an Ihrem Repo von Colab mit Datei> Kopie in GitHub speichern .... Der Speicherdialog sollte mit dem entsprechenden Repo und Zweig verknüpft sein. Fügen Sie eine aussagekräftige Festschreibungsnachricht hinzu.
  6. Navigieren Sie nach dem Speichern zu Ihrem Repo oder dem Tensorflow / Docs- Repo. GitHub sollte Sie auffordern , eine Pull-Anfrage zu erstellen.
  7. Die Pull-Anforderung wird von den Betreuern überprüft.

Übersetzungen

Das TensorFlow-Team arbeitet mit der Community und den Anbietern zusammen, um Übersetzungen für tensorflow.org bereitzustellen. Übersetzungen von Notizbüchern und anderen technischen Inhalten finden Sie im Tensorflow / docs-l10n GitHub-Repo. Bitte senden Sie Pull-Anfragen über das TensorFlow GitLocalize-Projekt .

Die englischen Dokumente sind die Quelle der Wahrheit, und Übersetzungen sollten diesen Anleitungen so genau wie möglich folgen. Das heißt, Übersetzungen werden für die Gemeinschaften geschrieben, denen sie dienen. Wenn die englische Terminologie, Phrasierung, der Stil oder der Ton nicht in eine andere Sprache übersetzt werden, verwenden Sie bitte eine für den Leser geeignete Übersetzung.

Die Sprachunterstützung wird durch eine Reihe von Faktoren bestimmt, darunter - ohne darauf beschränkt zu sein - Standortmetriken und -nachfrage, Community-Unterstützung, Englischkenntnisse , Präferenzen der Zielgruppe und andere Indikatoren. Da für jede unterstützte Sprache Kosten anfallen, werden nicht verwaltete Sprachen entfernt. Die Unterstützung für neue Sprachen wird im TensorFlow-Blog oder auf Twitter bekannt gegeben .

Wenn Ihre bevorzugte Sprache nicht unterstützt wird, können Sie gerne einen Community-Fork für Open Source-Mitwirkende unterhalten. Diese werden nicht auf tensorflow.org veröffentlicht.