Panduan gaya dokumentasi TensorFlow

Praktik terbaik

  • Fokus pada niat pengguna dan audiens.
  • Gunakan kata-kata sehari-hari dan buat kalimat pendek.
  • Gunakan konstruksi kalimat, kata-kata, dan kapitalisasi yang konsisten.
  • Gunakan judul dan daftar untuk membuat dokumen Anda lebih mudah dipindai.
  • Panduan Gaya Dokumen Pengembang Google sangat membantu.

Penurunan harga

Dengan beberapa pengecualian, TensorFlow menggunakan sintaks Markdown yang mirip dengan GitHub Flavoured Markdown (GFM). Bagian ini menjelaskan perbedaan antara sintaks GFM Markdown dan Markdown yang digunakan untuk dokumentasi TensorFlow.

Tulis tentang kode

Penyebutan kode sebaris

Letakkan `backticks` di sekitar simbol berikut saat digunakan dalam teks:

  • Nama argumen: `input` , `x` , `tensor`
  • Nama tensor yang dikembalikan: `output` , `idx` , `out`
  • Tipe data: `int32` , `float` , `uint8`
  • Referensi nama op lainnya dalam teks: `list_diff()` , `shuffle()`
  • Nama kelas: `tf.Tensor` , `Strategy`
  • Nama file: `image_ops.py` , `/path_to_dir/file_name`
  • Ekspresi atau kondisi matematika: `-1-input.dims() <= dim <= input.dims()`

Blok kode

Gunakan tiga backtick untuk membuka dan menutup blok kode. Secara opsional, tentukan bahasa pemrograman setelah grup backtick pertama, misalnya:


```python
# some python code here
```

Gunakan tautan relatif antar file dalam satu repositori GitHub. Sertakan ekstensi file.

Misalnya, file yang Anda baca ini berasal dari https://github.com/tensorflow/docs repositori. Oleh karena itu, ia dapat menggunakan jalur relatif untuk menautkan ke file lain di repositori yang sama seperti ini:

  • [Basics](../../guide/basics.ipynb) menghasilkan Basics .

Ini adalah pendekatan yang lebih disukai karena dengan cara ini semua tautan di tensorflow.org , GitHub , dan Colab berfungsi. Selain itu, pembaca tetap berada di situs yang sama saat mereka mengeklik tautan.

Untuk tautan ke file yang tidak ada di repositori saat ini, gunakan tautan Penurunan harga standar dengan URI lengkap. Pilih untuk menautkan ke URI tensorflow.org jika tersedia.

Untuk menautkan ke kode sumber, gunakan tautan yang dimulai dengan https://www.github.com/tensorflow/tensorflow/blob/master/ , diikuti dengan nama file yang dimulai dari akar GitHub.

Saat menautkan dari tensorflow.org , sertakan {:.external} pada tautan Penurunan harga sehingga simbol "tautan eksternal" ditampilkan.

  • [GitHub](https://github.com/tensorflow/docs){:.external} menghasilkan GitHub

Jangan sertakan parameter kueri URI di tautan:

  • Gunakan: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Bukan: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Gambar-gambar

Saran di bagian sebelumnya adalah untuk tautan ke halaman. Gambar ditangani secara berbeda.

Umumnya, Anda tidak boleh memeriksa gambar, dan sebagai gantinya menambahkan tim TensorFlow-Docs ke PR Anda, dan meminta mereka untuk menghosting gambar di tensorflow.org . Ini membantu menjaga ukuran repositori Anda tetap rendah.

Jika Anda mengirimkan gambar ke repositori Anda, perhatikan bahwa beberapa sistem tidak menangani jalur relatif ke gambar. Lebih suka menggunakan URL lengkap yang menunjuk ke lokasi akhirnya gambar di tensorflow.org .

Tautan API dikonversi saat situs dipublikasikan. Untuk menautkan ke halaman referensi API simbol, sertakan jalur simbol di backticks:

Jalur penuh sedikit lebih disukai kecuali jalur panjang. Jalur dapat disingkat dengan menghilangkan komponen jalur utama. Jalur sebagian akan dikonversi menjadi tautan jika:

  • Setidaknya ada satu . di jalan, dan
  • Jalur parsial unik dalam proyek.

Jalur API ditautkan untuk setiap proyek dengan API Python yang dipublikasikan di tensorflow.org . Anda dapat dengan mudah menautkan ke beberapa subproyek dari satu file dengan membungkus nama API dengan backticks. Sebagai contoh:

Untuk simbol dengan beberapa alias jalur, ada sedikit preferensi untuk jalur yang cocok dengan halaman API di tensorflow.org . Semua alias akan dialihkan ke halaman yang benar.

Matematika di Markdown

Anda dapat menggunakan MathJax dalam TensorFlow saat mengedit file penurunan harga, tetapi perhatikan hal berikut:

  • MathJax merender dengan benar di tensorflow.org .
  • MathJax tidak merender dengan benar di GitHub.
  • Notasi ini dapat mengganggu pengembang yang tidak dikenal.
  • Untuk konsistensi tensorflow.org mengikuti aturan yang sama seperti Jupyter/Colab.

Gunakan $$ di sekitar blok MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Bungkus ekspresi MathJax sebaris dengan $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Ini adalah contoh ekspresi MathJax sebaris: l10n \( 2 \times 2 = 4 \)

Pembatas \\( ... \\) juga berfungsi untuk matematika sebaris, tetapi bentuk $ terkadang lebih mudah dibaca.

gaya prosa

Jika Anda akan menulis atau mengedit sebagian besar dokumentasi naratif, harap baca Panduan Gaya Dokumentasi Pengembang Google .

Prinsip gaya yang baik

  • Periksa ejaan dan tata bahasa dalam kontribusi Anda. Sebagian besar editor menyertakan pemeriksa ejaan atau memiliki plugin pemeriksa ejaan yang tersedia. Anda juga dapat menempelkan teks Anda ke dalam Google Doc atau perangkat lunak dokumen lainnya untuk pemeriksaan ejaan dan tata bahasa yang lebih kuat.
  • Gunakan suara yang santai dan ramah. Tulis dokumentasi TensorFlow seperti percakapan—seolah-olah Anda sedang berbicara satu lawan satu dengan orang lain. Gunakan nada yang mendukung dalam artikel.
  • Hindari penafian, opini, dan penilaian nilai. Kata-kata seperti "mudah", "hanya", dan "sederhana" sarat dengan asumsi. Sesuatu mungkin tampak mudah bagi Anda, tetapi sulit bagi orang lain. Cobalah untuk menghindari ini bila memungkinkan.
  • Gunakan kalimat sederhana, to the point tanpa jargon yang rumit. Kalimat majemuk, rantai klausa, dan idiom khusus lokasi dapat membuat teks sulit untuk dipahami dan diterjemahkan. Jika sebuah kalimat dapat dibagi menjadi dua, mungkin harus. Hindari titik koma. Gunakan daftar peluru bila perlu.
  • Berikan konteks. Jangan gunakan singkatan tanpa menjelaskannya. Jangan menyebutkan proyek non-TensorFlow tanpa menautkannya. Jelaskan mengapa kode ditulis seperti itu.

Panduan penggunaan

operasi

Dalam file penurunan harga, gunakan # ⇒ alih-alih satu tanda sama dengan ketika Anda ingin menunjukkan apa yang dikembalikan oleh op.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

Di buku catatan, tampilkan hasilnya alih-alih menambahkan komentar (Jika ekspresi terakhir di sel buku catatan tidak ditetapkan ke variabel, itu akan ditampilkan secara otomatis.)

Dalam referensi API, dokumen lebih suka menggunakan doctest untuk menampilkan hasil.

Tensor

Saat Anda berbicara tentang tensor secara umum, jangan menggunakan huruf besar untuk kata tensor . Saat Anda berbicara tentang objek tertentu yang disediakan atau dikembalikan dari operasi, maka Anda harus menggunakan huruf besar pada kata Tensor dan menambahkan tanda centang di sekitarnya karena Anda sedang membicarakan objek Tensor .

Jangan gunakan kata Tensor (jamak) untuk mendeskripsikan beberapa objek Tensor kecuali Anda benar-benar berbicara tentang objek Tensors . Sebagai gantinya, ucapkan "daftar (atau kumpulan) objek Tensor ".

Gunakan bentuk kata untuk merinci sumbu tensor, dan perlihatkan bentuk dalam tanda kurung siku dengan tanda centang belakang. Sebagai contoh:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Seperti di atas, lebih suka "sumbu" atau "indeks" daripada "dimensi" ketika berbicara tentang elemen bentuk Tensor . Kalau tidak, mudah untuk mengacaukan "dimensi" dengan dimensi ruang vektor. Sebuah "vektor tiga dimensi" memiliki sumbu tunggal dengan panjang 3.