Bu sayfa, Cloud Translation API ile çevrilmiştir.

TensorFlow API belgelerine katkıda bulunun

Test edilebilir dokümanlar

TensorFlow, Python belge dizelerindeki kod parçacıklarını test etmek için DocTest'i kullanır. Snippet'in çalıştırılabilir Python kodu olması gerekir. Testi etkinleştirmek için satırın başına >>> (üç sol açılı parantez) ekleyin. Örneğin, array_ops.py kaynak dosyasındaki tf.concat işlevinden bir alıntı:

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>

Referans dokümantasyon kalitesini değerlendirmek için TensorFlow 2 API Dokümanları tavsiyesinin örnek bölümüne bakın. (Bu sayfadaki Görev İzleyicinin artık kullanılmadığını unutmayın.)

Kodu DocTest ile test edilebilir hale getirin

Şu anda birçok belge dizisi kodu tanımlamak için geri işaretler (```) kullanıyor. Kodu DocTest ile test edilebilir hale getirmek için:

Geri tırnakları (```) kaldırın ve her satırın önündeki sol parantezleri (>>>) kullanın. Devam eden satırların önünde (...) kullanın.
Tensorflow.org'da düzgün bir şekilde oluşturmak için DocTest parçacıklarını Markdown metninden ayırmak için yeni bir satır ekleyin.

Özelleştirmeler

TensorFlow, yerleşik doctest mantığında birkaç özelleştirme kullanır:

Float değerlerini metin olarak karşılaştırmaz: Float değerleri metinden çıkarılır ve allclose ile liberal atol ve rtol toleransları kullanılarak karşılaştırılır. Bu şunları sağlar:
- Daha net belgeler - Yazarların ondalık basamakların tamamını eklemesine gerek yoktur.
- Daha sağlam testler - Temel uygulamadaki sayısal değişiklikler hiçbir zaman doctest'in başarısız olmasına neden olmamalıdır.
Yalnızca yazarın bir satır için çıktı içermesi durumunda çıktıyı kontrol eder. Bu, dokümanların daha net olmasını sağlar çünkü yazarların genellikle bunların yazdırılmasını önlemek için alakasız ara değerleri yakalamasına gerek yoktur.

Dokümantasyonla ilgili hususlar

Genel : Doctest'in amacı dokümantasyon sağlamak ve dokümantasyonun çalıştığını doğrulamaktır. Bu, birim testinden farklıdır. Bu yüzden:
- Örnekleri basit tutun.
- Uzun veya karmaşık çıktılardan kaçının.
- Mümkünse yuvarlak sayıları kullanın.
Çıktı biçimi : Parçacığın çıktısının, çıktıyı oluşturan kodun hemen altında olması gerekir. Ayrıca, belge dizisindeki çıktının, kod yürütüldükten sonraki çıktıya tam olarak eşit olması gerekir. Yukarıdaki örneğe bakın. Ayrıca DocTest belgelerindeki bu bölüme göz atın. Çıkış 80 satır sınırını aşarsa ekstra çıkışı yeni satıra koyabilirsiniz; DocTest bunu tanıyacaktır. Örneğin aşağıdaki çok hatlı bloklara bakın.
Globals : `tf` , np ve os modülleri TensorFlow'un DocTest'inde her zaman mevcuttur.
Sembolleri kullan : DocTest'te aynı dosyada tanımlanan sembollere doğrudan erişebilirsiniz. Geçerli dosyada tanımlanmayan bir sembolü kullanmak için lütfen xxx yerine TensorFlow'un genel API'si tf.xxx kullanın. Aşağıdaki örnekte görebileceğiniz gibi `random.normal` `tf.random.normal` üzerinden erişilmektedir. Bunun nedeni `random.normal` in NewLayer görünmemesidir.
```
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=...>
  """
```
Kayan nokta değerleri : TensorFlow doctest, sonuç dizelerinden kayan nokta değerlerini çıkarır ve makul toleranslarla ( atol=1e-6 , rtol=1e-6 ) np.allclose kullanarak karşılaştırır. Bu şekilde yazarların, sayısal sorunlar nedeniyle başarısızlıklara neden olan aşırı hassas doküman dizileri konusunda endişelenmelerine gerek kalmaz. Beklenen değeri yapıştırmanız yeterlidir.

Deterministik olmayan çıktı : Belirsiz kısımlar için üç nokta ( ... ) kullanın; DocTest bu alt dizeyi yok sayacaktır.

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

Çok satırlı bloklar : DocTest, tek ve çok satırlı ifadeler arasındaki fark konusunda katıdır. Aşağıdaki (...) kullanımına dikkat edin:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

İstisnalar : Ortaya çıkan İstisna dışında istisna ayrıntıları göz ardı edilir. Daha fazla ayrıntı için buna bakın.

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'>`.

Tf-doctest'in proje yerel kopyasını kullanın.

TensorFlow'daki bazı API'ler harici bir projeden gelir:

tf.estimator ( tensorflow_estimator'dan )
tf.summary tensorboard )
tf.keras.preprocessing ( keras-preprocessing'den )

Harici bir proje üzerinde veya harici bir projede barındırılan TensorFlow API'leri üzerinde çalışıyorsanız, bu projenin kendi yerel tf_doctest kopyası olmadığı ve TensorFlow'un kopyası yerine bu kopyayı kullanmadığınız sürece bu talimatlar çalışmaz.

Örneğin: tf_estimator_doctest.py .

Yerel makinenizde test edin

Doküman dizesindeki kodu yerel olarak test etmenin iki yolu vardır:

Yalnızca bir sınıfın/işlevin/yöntemin belge dizesini değiştiriyorsanız, o dosyanın yolunu tf_doctest.py'ye ileterek bunu test edebilirsiniz. Örneğin:
```
python tf_doctest.py --file=<file_path>
```
Bu, TensorFlow'un yüklü sürümünü kullanarak çalıştıracaktır. Test ettiğiniz kodun aynısını çalıştırdığınızdan emin olmak için:
- Güncel bir tf-nightly pip install -U tf-nightly
- Çekme isteğinizi TensorFlow'un ana dalından yakın zamanda yapılan bir çekme işlemine göre yeniden temellendirin.
Bir sınıfın/işlev/yöntemin kodunu ve belge dizisini değiştiriyorsanız, kaynaktan TensorFlow oluşturmanız gerekecektir. Kaynaktan derleme kurulumu yapıldıktan sonra testleri çalıştırabilirsiniz:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
veya
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
--module tensorflow.python göredir.