Berkontribusi pada dokumentasi TensorFlow API

Dokumen 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 tanda 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>

Catatan: TensorFlow DocTest menggunakan TensorFlow 2 dan Python 3.

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

Jadikan kode dapat diuji dengan DocTest

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

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

Kustomisasi

TensorFlow menggunakan beberapa penyesuaian pada logika doctest bawaan:

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

Pertimbangan doktrin

• Secara keseluruhan : Tujuan dari doctest adalah untuk menyediakan dokumentasi, dan memastikan bahwa dokumentasi tersebut berfungsi. Ini berbeda dengan pengujian unit. Jadi:
  • Buat contoh tetap sederhana.
  • Hindari keluaran yang panjang atau rumit.
  • Gunakan angka bulat jika memungkinkan.
• Format keluaran : Keluaran cuplikan harus berada tepat di bawah kode yang menghasilkan keluaran. Selain itu, keluaran dalam docstring harus sama persis dengan keluaran setelah kode dieksekusi. Lihat contoh di atas. Lihat juga bagian ini di dokumentasi DocTest. Jika keluaran melebihi batas 80 baris, Anda dapat memasukkan keluaran tambahan pada baris baru dan DocTest akan mengenalinya. Misalnya, lihat blok multi-baris di bawah.
• Global : Modul `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, harap gunakan API publik TensorFlow tf.xxx bukan 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 : Dokumen TensorFlow mengekstrak nilai float dari string hasil, dan membandingkannya menggunakan np.allclose dengan toleransi yang masuk akal ( 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 tempelkan nilai yang diharapkan.

• Output non-deterministik : Gunakan elipsis( ... ) untuk bagian yang tidak pasti dan DocTest akan mengabaikan substring tersebut.

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

• Blok multi-baris : DocTest sangat ketat dalam membedakan 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 tf-doctest lokal proyek.

Catatan: Utilitas tf-doctest hanya disiapkan untuk menguji file sumber dalam repositori tensorflow . Jika file yang Anda edit ada di TensorFlow, Anda dapat melompat ke bagian berikutnya. Jika tidak, teruslah membaca bagian ini.

Beberapa API di TensorFlow berasal dari proyek eksternal:

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

Jika Anda mengerjakan proyek eksternal, atau pada TensorFlow API yang ditempatkan di proyek eksternal, petunjuk ini tidak akan berfungsi kecuali proyek tersebut memiliki salinan lokal tf_doctest sendiri, dan Anda menggunakan salinan tersebut, bukan salinan 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 suatu kelas/fungsi/metode, maka Anda dapat mengujinya dengan meneruskan jalur file tersebut ke tf_doctest.py . Misalnya:

  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 tf-nightly pip install -U tf-nightly terbaru
  • Ubah dasar permintaan penarikan Anda menjadi penarikan terbaru dari cabang master TensorFlow .

• Jika Anda mengubah kode dan docstring suatu kelas/fungsi/metode, Anda perlu membuat TensorFlow dari source . Setelah Anda menyiapkan untuk membangun dari sumber, Anda dapat menjalankan pengujian:

  bazel run //tensorflow/tools/docs:tf_doctest

  atau

  bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops

  --module relatif terhadap tensorflow.python .