Halaman ini diterjemahkan oleh Cloud Translation API.

Berkontribusi pada dokumentasi API TensorFlow

Docstring yang dapat diuji

TensorFlow menggunakan DocTest untuk menguji cuplikan kode dalam dokumen Python. Cuplikan harus berupa kode Python yang dapat dieksekusi. Untuk mengaktifkan pengujian, tambahkan baris dengan >>> (tiga kurung sudut kiri). Misalnya, berikut kutipan dari fungsi tf.concat di file sumber array_ops.py :

def concat(values, axis, name="concat"):
  """Concatenates tensors along one dimension.
  ...

  >>> t1 = [[1, 2, 3], [4, 5, 6]]
  >>> t2 = [[7, 8, 9], [10, 11, 12]]
  >>> concat([t1, t2], 0)
  <tf.Tensor: shape=(4, 3), dtype=int32, numpy=
  array([[ 1,  2,  3],
         [ 4,  5,  6],
         [ 7,  8,  9],
         [10, 11, 12]], dtype=int32)>

  <... more description or code snippets ...>

  Args:
    values: A list of `tf.Tensor` objects or a single `tf.Tensor`.
    axis: 0-D `int32` `Tensor`.  Dimension along which to concatenate. Must be
      in the range `[-rank(values), rank(values))`. As in Python, indexing for
      axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers
      to `axis`-th dimension. And negative axis refers to `axis +
      rank(values)`-th dimension.
    name: A name for the operation (optional).

    Returns:
      A `tf.Tensor` resulting from concatenation of the input tensors.
  """

  <code here>

Untuk menilai kualitas dokumentasi referensi, lihat bagian contoh saran Dokumen API TensorFlow 2 . (Perhatikan bahwa Pelacak Tugas pada lembar ini tidak lagi digunakan.)

Jadikan kode dapat diuji dengan DocTest

Saat ini, banyak docstring menggunakan backticks (```) untuk mengidentifikasi kode. Untuk membuat kode dapat diuji dengan DocTest:

Hapus tanda centang belakang (```) dan gunakan tanda kurung siku kiri (>>>) di depan setiap baris. Gunakan (...) di depan baris lanjutan.
Tambahkan baris baru untuk memisahkan cuplikan DocTest dari teks Penurunan harga untuk dirender dengan benar di tensorflow.org.

Kustomisasi

TensorFlow menggunakan beberapa penyesuaian pada logika doctest bawaan:

Itu tidak membandingkan nilai float sebagai teks: Nilai float diekstraksi dari teks dan dibandingkan menggunakan allclose dengan atol liberal dan rtol . Ini memungkinkan:
- Dokumen yang lebih jelas - Penulis tidak perlu menyertakan semua tempat desimal.
- Tes yang lebih kuat - Perubahan numerik dalam implementasi yang mendasarinya tidak boleh menyebabkan doctest gagal.
Itu hanya memeriksa output jika penulis menyertakan output untuk sebuah baris. Ini memungkinkan dokumen yang lebih jelas karena penulis biasanya tidak perlu menangkap nilai perantara yang tidak relevan untuk mencegahnya dicetak.

Pertimbangan Dokstring

Keseluruhan : Tujuan dari doctest adalah untuk menyediakan dokumentasi, dan memastikan bahwa dokumentasi tersebut berfungsi. Ini berbeda dengan pengujian unit. Jadi:
- Buatlah contoh yang sederhana.
- Hindari keluaran yang panjang atau rumit.
- Gunakan angka bulat jika memungkinkan.
Format keluaran : Keluaran cuplikan harus tepat di bawah kode yang menghasilkan keluaran. Juga, output dalam docstring harus sama persis dengan output setelah kode dieksekusi. Lihat contoh di atas. Juga, periksa bagian ini dalam dokumentasi DocTest. Jika output melebihi batas 80 baris, Anda dapat menempatkan output tambahan pada baris baru dan DocTest akan mengenalinya. Misalnya, lihat blok multi-baris di bawah ini.
Globals : `tf` , np , dan os selalu tersedia di DocTest TensorFlow.
Gunakan simbol : Di DocTest Anda dapat langsung mengakses simbol yang ditentukan dalam file yang sama. Untuk menggunakan simbol yang tidak ditentukan dalam file saat ini, gunakan API publik tf.xxx alih-alih xxx . Seperti yang Anda lihat pada contoh di bawah, `random.normal` diakses melalui `tf.random.normal` . Ini karena `random.normal` tidak terlihat di NewLayer .
```
def NewLayer():
  """This layer does cool stuff.

  Example usage:

  >>> x = tf.random.normal((1, 28, 28, 3))
  >>> new_layer = NewLayer(x)
  >>> new_layer
  <tf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...>
  """
```
Nilai floating point : Doctest TensorFlow mengekstrak nilai float dari string hasil, dan membandingkan menggunakan np.allclose dengan toleransi yang wajar ( atol=1e-6 , rtol=1e-6 ). Dengan cara ini penulis tidak perlu khawatir tentang dokumen yang terlalu presisi yang menyebabkan kegagalan karena masalah numerik. Cukup tempel di nilai yang diharapkan.

Output non-deterministik : Gunakan Ellipsis( ... ) untuk bagian yang tidak pasti dan DocTest akan mengabaikan substring itu.

x = tf.random.normal((1,))
print(x)
    <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>

Blok multi-baris : DocTest ketat tentang perbedaan antara pernyataan tunggal dan multi-baris. Perhatikan penggunaan (...) di bawah ini:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

Pengecualian : Detail Pengecualian diabaikan kecuali Pengecualian yang dimunculkan. Lihat ini untuk lebih jelasnya.

np_var = np.array([1, 2])
tf.keras.backend.is_keras_tensor(np_var)
    Traceback (most recent call last):

    ValueError: Unexpectedly found an instance of type `<class 'numpy.ndarray'>`.

Gunakan salinan lokal proyek dari tf-doctest.

Beberapa API di TensorFlow berasal dari proyek eksternal:

tf.estimator (dari tensorflow_estimator )
tf.summary tensorboard )
tf.keras.preprocessing (dari keras-preprocessing )

Jika Anda sedang mengerjakan proyek eksternal, atau pada API TensorFlow yang disimpan di proyek eksternal, petunjuk ini tidak akan berfungsi kecuali jika proyek tersebut memiliki salinan lokal tf_doctest , dan Anda menggunakan salinan itu alih-alih milik TensorFlow.

Misalnya: tf_estimator_doctest.py .

Uji pada mesin lokal Anda

Ada dua cara untuk menguji kode di docstring secara lokal:

Jika Anda hanya mengubah docstring dari kelas/fungsi/metode, maka Anda dapat mengujinya dengan meneruskan jalur file itu ke tf_doctest.py . Sebagai contoh:
```
python tf_doctest.py --file=<file_path>
```
Ini akan menjalankannya menggunakan versi TensorFlow yang Anda instal. Untuk memastikan Anda menjalankan kode yang sama dengan yang Anda uji:
- Gunakan instalasi pip tf- nightly terbaru pip install -U tf-nightly
- Basis ulang permintaan tarik Anda ke tarikan terbaru dari cabang master TensorFlow .
Jika Anda mengubah kode dan docstring class/function/method, maka Anda perlu membangun TensorFlow dari source . Setelah Anda menyiapkan untuk membangun dari sumber, Anda dapat menjalankan tes:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
atau
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
--module relatif terhadap tensorflow.python .