Thanks for tuning in to Google I/O. View all sessions on demandWatch on demand

Berkontribusi pada dokumentasi TensorFlow

TensorFlow menyambut baik kontribusi dokumentasi—jika Anda meningkatkan dokumentasi, Anda meningkatkan library TensorFlow itu sendiri. Dokumentasi di tensorflow.org termasuk dalam kategori berikut:

Beberapa proyek TensorFlow menyimpan file sumber dokumentasi di dekat kode dalam repositori terpisah, biasanya di direktori docs/ . Lihat file CONTRIBUTING.md proyek atau hubungi pengelola untuk berkontribusi.

Untuk berpartisipasi dalam komunitas dokumen TensorFlow:

referensi API

Untuk detailnya, gunakan panduan kontributor dokumen TensorFlow API . Ini menunjukkan cara menemukan file sumber dan mengedit docstring simbol. Banyak halaman referensi API di tensorflow.org menyertakan tautan ke file sumber tempat simbol didefinisikan. Docstrings mendukung penurunan harga dan dapat (kurang-lebih) dipratinjau menggunakan pratinjau penurunan harga apa pun.

Versi dan cabang

Versi referensi API situs default ke biner stabil terbaru—ini cocok dengan paket yang diinstal dengan pip install tensorflow .

Paket TensorFlow default dibuat dari cabang stabil rX.x di repo tensorflow/tensorflow utama. Dokumentasi referensi dihasilkan dari komentar kode dan docstrings dalam kode sumber untuk Python , C++ , dan Java .

Dokumentasi TensorFlow versi sebelumnya tersedia sebagai cabang rX.x di repositori TensorFlow Docs. Cabang-cabang ini ditambahkan ketika versi baru dirilis.

Buat dokumen API

Referensi python

Paket tensorflow_docs menyertakan generator untuk dokumen referensi API Python . Untuk memasang:

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

Untuk membuat dokumen referensi TensorFlow 2, gunakan 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

dokumentasi naratif

Panduan dan tutorial TensorFlow ditulis sebagai file penurunan harga dan notebook Jupyter interaktif. Notebook dapat dijalankan di browser Anda menggunakan Google Colaboratory . Dokumen naratif di tensorflow.org dibuat dari cabang master tensorflow/docs . Versi lama tersedia di GitHub di cabang rilis rX.x

Perubahan sederhana

Cara termudah untuk membuat pembaruan dokumentasi langsung ke file Markdown adalah dengan menggunakan editor file berbasis web GitHub . Jelajahi repositori tensorflow/docs untuk menemukan Markdown yang kira-kira sesuai dengan struktur URL tensorflow.org . Di sudut kanan atas tampilan file, klik ikon pensil untuk membuka editor file. Edit file dan kemudian kirimkan permintaan tarik baru.

Siapkan repo Git lokal

Untuk pengeditan multi-file atau pembaruan yang lebih kompleks, lebih baik menggunakan alur kerja Git lokal untuk membuat permintaan tarik.

Langkah-langkah Git berikut hanya diperlukan saat pertama kali Anda menyiapkan proyek lokal.

Garpu repo tensorflow/docs

Pada halaman GitHub tensorflow/docs , klik tombol Fork untuk membuat salinan repo Anda sendiri di bawah akun GitHub Anda. Setelah bercabang, Anda bertanggung jawab untuk memperbarui salinan repo Anda dengan repo TensorFlow upstream.

Kloning repo Anda

Unduh salinan username jarak jauh Anda /docs repo ke mesin lokal Anda. Ini adalah direktori kerja tempat Anda akan membuat perubahan:

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

Tambahkan repo upstream untuk tetap up-to-date (opsional)

Untuk menjaga agar repositori lokal Anda tetap sinkron dengan tensorflow/docs , tambahkan remote upstream untuk mendownload perubahan terbaru.

Tambahkan jarak jauh:

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)

Untuk memperbaharui:

git checkout master
git pull upstream master

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

Alur kerja GitHub

1. Buat cabang baru

Setelah Anda memperbarui repo Anda dari tensorflow/docs , buat cabang baru dari cabang master lokal:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Lakukan perubahan

Edit file di editor favorit Anda dan ikuti panduan gaya dokumentasi TensorFlow .

Komit perubahan file Anda:

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

Tambahkan lebih banyak komit, jika perlu.

3. Buat permintaan tarik

Unggah cabang lokal Anda ke repo GitHub jarak jauh Anda (github.com/ username /docs):

git push

Setelah push selesai, sebuah pesan mungkin menampilkan URL untuk secara otomatis mengirimkan permintaan tarik ke repo upstream. Jika tidak, buka repo tensorflow/docs —atau repo Anda sendiri—dan GitHub akan meminta Anda untuk membuat pull request.

4. Tinjau

Pengelola dan kontributor lainnya akan meninjau permintaan tarik Anda. Silakan berpartisipasi dalam diskusi dan buat perubahan yang diminta. Saat pull request Anda disetujui, permintaan tersebut akan digabungkan ke dalam repo dokumen TensorFlow upstream.

Ada langkah penerbitan terpisah untuk memperbarui tensorflow.org dari repo GitHub. Biasanya, perubahan dikumpulkan bersama dan situs diperbarui secara teratur.

Buku catatan interaktif

Meskipun dimungkinkan untuk mengedit file JSON notebook dengan editor file berbasis web GitHub , tidak disarankan karena format JSON yang salah dapat merusak file. Pastikan untuk menguji notebook sebelum mengirimkan permintaan tarik.

Google Colaboratory adalah lingkungan notebook yang dihosting yang memudahkan untuk mengedit—dan menjalankan—dokumentasi notebook. Notebook di GitHub dimuat di Google Colab dengan meneruskan jalur ke URL Colab, misalnya, notebook yang terletak di GitHub di sini: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /klasifikasi.ipynb
dapat dimuat ke Google Colab di URL ini: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Ada ekstensi Chrome Buka di Colab yang melakukan penggantian URL ini saat menjelajahi buku catatan di GitHub. Ini berguna saat membuka buku catatan di garpu repo Anda, karena tombol atas selalu tertaut ke cabang master TensorFlow Docs.

Pemformatan buku catatan

Alat pemformatan buku catatan membuat perbedaan sumber buku catatan Jupyter konsisten dan lebih mudah untuk ditinjau. Karena lingkungan penulisan buku catatan berbeda dalam hal keluaran file, lekukan, metadata, dan bidang lain yang tidak ditentukan; nbfmt menggunakan default berpendirian dengan preferensi untuk alur kerja Colab dokumen TensorFlow. Untuk memformat buku catatan, instal alat notebook dokumen TensorFlow dan jalankan alat 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 [...]

Untuk proyek dokumen TensorFlow, notebook tanpa sel keluaran dieksekusi dan diuji; notebook dengan sel keluaran yang disimpan diterbitkan apa adanya. nbfmt menghormati status notebook dan menggunakan opsi --remove_outputs untuk menghapus sel output secara eksplisit.

Untuk membuat buku catatan baru, salin dan edit templat buku catatan dokumen TensorFlow .

Edit di Colab

Dalam lingkungan Google Colab, klik dua kali sel untuk mengedit teks dan blok kode. Sel teks menggunakan penurunan harga dan harus mengikuti panduan gaya dokumen TensorFlow .

Unduh file buku catatan dari Colab dengan File > Unduh .pynb . Komit file ini ke repo Git lokal Anda dan kirim permintaan tarik.

Untuk membuat buku catatan baru, salin dan edit templat buku catatan TensorFlow .

Alur kerja Colab-GitHub

Alih-alih mengunduh file buku catatan dan menggunakan alur kerja Git lokal, Anda dapat mengedit dan memperbarui repo GitHub bercabang langsung dari Google Colab:

  1. Di repo username /docs bercabang Anda, gunakan UI web GitHub untuk membuat cabang baru .
  2. Navigasikan ke file buku catatan untuk mengedit.
  3. Buka buku catatan di Google Colab: gunakan pertukaran URL atau ekstensi Chrome Buka di Colab .
  4. Edit buku catatan di Colab.
  5. Lakukan perubahan pada repo Anda dari Colab dengan File > Save a copy in GitHub... . Dialog simpan harus tertaut ke repo dan cabang yang sesuai. Tambahkan pesan komit yang berarti.
  6. Setelah menyimpan, menelusuri repo Anda atau repo tensorflow/docs , GitHub akan meminta Anda untuk membuat pull request.
  7. Permintaan tarik ditinjau oleh pengelola.

Terjemahan

Tim TensorFlow bekerja dengan komunitas dan vendor untuk menyediakan terjemahan untuk tensorflow.org. Terjemahan buku catatan dan konten teknis lainnya terdapat di repo GitHub tensorflow/docs-l10n . Harap kirimkan permintaan tarik melalui proyek TensorFlow GitLocalize .

Dokumen bahasa Inggris adalah sumber kebenaran dan terjemahan harus mengikuti panduan ini sedekat mungkin. Konon, terjemahan ditulis untuk komunitas yang mereka layani. Jika terminologi, frasa, gaya, atau nada bahasa Inggris tidak diterjemahkan ke bahasa lain, harap gunakan terjemahan yang sesuai untuk pembaca.

Dukungan bahasa ditentukan oleh sejumlah faktor termasuk—namun tidak terbatas pada—metrik dan permintaan situs, dukungan komunitas, kecakapan bahasa Inggris , preferensi audiens, dan indikator lainnya. Karena setiap bahasa yang didukung dikenakan biaya, bahasa yang tidak dikelola akan dihapus. Dukungan untuk bahasa baru akan diumumkan di blog TensorFlow atau Twitter .

Jika bahasa pilihan Anda tidak didukung, Anda dipersilakan untuk memelihara garpu komunitas untuk kontributor sumber terbuka. Ini tidak dipublikasikan ke tensorflow.org.