Berkontribusi pada dokumentasi TensorFlow

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

• Referensi API —Dokumen referensi API dihasilkan dari dokumen dalam kode sumber TensorFlow .
• Dokumentasi naratif —Ini adalah tutorial , panduan , dan tulisan lain yang bukan bagian dari kode TensorFlow. Dokumentasi ini ada di repositori GitHub tensorflow/docs .
• Terjemahan komunitas —Ini adalah panduan dan tutorial yang diterjemahkan oleh komunitas. Semua terjemahan komunitas ada di repo tensorflow/docs .

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

Untuk berpartisipasi dalam komunitas dokumen TensorFlow:

• Tonton repositori GitHub tensorflow/docs .
• Ikuti tag dokumen di Forum TensorFlow .

Referensi API

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

Versi dan cabang

Versi referensi API situs ini defaultnya adalah 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 dokumen 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

Catatan: Langkah ini tidak diperlukan untuk mengedit atau melihat pratinjau dokumen API, hanya untuk menghasilkan HTML yang digunakan di tensorflow.org.

Referensi piton

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

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

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

Catatan: Skrip ini menggunakan paket TensorFlow yang terinstal untuk menghasilkan dokumen dan hanya berfungsi untuk TensorFlow 2.x.

Dokumentasi naratif

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

Perubahan sederhana

Cara termudah untuk membuat pembaruan dokumentasi langsung pada file Markdown adalah dengan menggunakan editor file berbasis web GitHub. Telusuri repositori tensorflow/docs untuk menemukan Penurunan Harga yang kira-kira sesuai dengan struktur URL tensorflow.org . Di pojok kanan atas tampilan file, klik ikon pensil untuk membuka editor file. Edit file lalu kirimkan permintaan penarikan 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.

Catatan: Git adalah sistem kontrol versi sumber terbuka (VCS) yang digunakan untuk melacak perubahan pada kode sumber. GitHub adalah layanan online yang menyediakan alat kolaborasi yang bekerja dengan Git. Lihat Bantuan GitHub untuk menyiapkan akun GitHub Anda dan memulai.

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 selalu memperbarui salinan repo dengan repo TensorFlow upstream.

Kloning repo Anda

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

git clone [e-mail]:username/docs
cd ./docs

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

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

Catatan: Pastikan untuk memperbarui repo lokal Anda sebelum memulai kontribusi. Sinkronisasi reguler ke upstream mengurangi kemungkinan konflik penggabungan saat Anda mengirimkan permintaan penarikan.

Tambahkan jarak jauh:

git remote add upstream [e-mail]:tensorflow/docs.git

# View remote repos
git remote -v
origin    [e-mail]:username/docs.git (fetch)
origin    [e-mail]:username/docs.git (push)
upstream  [e-mail]:tensorflow/docs.git (fetch)
upstream  [e-mail]:tensorflow/docs.git (push)

Untuk memperbarui:

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 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 komitmen, jika diperlukan.

3. Buat permintaan tarik

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

git push

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

4. Tinjauan

Pengelola dan kontributor lainnya akan meninjau permintaan penarikan Anda. Silakan berpartisipasi dalam diskusi dan lakukan perubahan yang diminta. Jika permintaan penarikan Anda disetujui, permintaan tersebut akan digabungkan ke dalam repo dokumen TensorFlow upstream.

Berhasil: Perubahan Anda telah diterima pada dokumentasi TensorFlow.

Ada langkah penerbitan terpisah untuk memperbarui tensorflow.org dari repo GitHub. Biasanya, perubahan digabungkan dan situs diperbarui secara berkala.

Buku catatan interaktif

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

Google Colaboratory adalah lingkungan buku catatan yang dihosting yang memudahkan pengeditan—dan menjalankan—dokumentasi buku catatan. 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 substitusi URL ini saat menjelajahi buku catatan di GitHub. Ini berguna saat membuka buku catatan di fork 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 ditinjau. Karena lingkungan pembuatan buku catatan berbeda dalam hal keluaran file, indentasi, metadata, dan bidang lain yang tidak ditentukan; nbfmt menggunakan default yang disetujui dengan preferensi untuk alur kerja Colab dokumen TensorFlow. Untuk memformat buku catatan, instal alat buku catatan TensorFlow docs 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; buku catatan dengan sel keluaran yang disimpan diterbitkan apa adanya. nbfmt menghormati status notebook dan menggunakan opsi --remove_outputs untuk menghapus sel keluaran 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 Markdown dan harus mengikuti panduan gaya dokumen TensorFlow .

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

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

Alur kerja Colab-GitHub

Daripada mendownload file notebook dan menggunakan alur kerja Git lokal, Anda dapat mengedit dan memperbarui repo GitHub bercabang langsung dari Google Colab:

1. Di repo username /docs Anda yang bercabang, gunakan UI web GitHub untuk membuat cabang baru .
2. Navigasikan ke file buku catatan untuk diedit.
3. Buka buku catatan di Google Colab: gunakan pertukaran URL atau ekstensi Buka di Colab Chrome.
4. Edit buku catatan di Colab.
5. Terapkan perubahan pada repo Anda dari Colab dengan File > Simpan salinan di GitHub... . Dialog penyimpanan harus tertaut ke repo dan cabang yang sesuai. Tambahkan pesan komit yang bermakna.
6. Setelah menyimpan, telusuri repo Anda atau repo tensorflow/docs , GitHub akan meminta Anda membuat permintaan tarik.
7. Permintaan penarikan ditinjau oleh pengelola.

Berhasil: Perubahan Anda telah diterima pada dokumentasi TensorFlow.

Terjemahan

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

Dokumen berbahasa Inggris adalah sumber kebenaran dan terjemahannya harus mengikuti panduan ini sedekat mungkin. Meskipun demikian, terjemahannya 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, kemahiran 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 forum komunitas untuk kontributor sumber terbuka. Ini tidak dipublikasikan ke tensorflow.org.