TensorFlow dokümantasyon stili kılavuzu

En iyi uygulamalar

  • Kullanıcı amacına ve hedef kitleye odaklanın.
  • Günlük kelimeler kullanın ve cümleleri kısa tutun.
  • Cümle yapısında, kelime seçiminde ve büyük harf kullanımında tutarlılık sağlayın.
  • Belgelerinizin taranmasını kolaylaştırmak için başlıklar ve listeler kullanın.
  • Google Geliştirici Dokümanları Stil Kılavuzu faydalıdır.

Markdown

Birkaç istisna dışında, TensorFlow, GitHub Flavored Markdown (GFM) ile benzer bir Markdown sözdizimi kullanır. Bu bölüm, GFM Markdown sözdizimi ile TensorFlow dokümantasyonunda kullanılan Markdown arasındaki farkları açıklamaktadır.

Kod hakkında yazın

Kodun satır içi atıfları

Aşağıdaki sembolleri metin içinde kullanırken `ters tırnak` işaretlerinin etrafına `backticks` koyun:

  • Argüman adları: `input` , `x` , `tensor`
  • Döndürülen tensör adları: `output` , `idx` , `out`
  • Veri tipleri: `int32` , `float` , `uint8`
  • Metinde geçen diğer işlem adları: `list_diff()` , `shuffle()`
  • Sınıf adları: `tf.Tensor` , `Strategy`
  • Dosya adı: `image_ops.py` , `/path_to_dir/file_name`
  • Matematiksel ifadeler veya koşullar: `-1-input.dims() <= dim <= input.dims()`

Kod blokları

Kod bloğunu açmak ve kapatmak için üç ters tırnak işareti kullanın. İsteğe bağlı olarak, ilk ters tırnak işareti grubundan sonra programlama dilini belirtebilirsiniz, örneğin:


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

Tek bir GitHub deposundaki dosyalar arasında göreceli bağlantılar kullanın. Dosya uzantısını da ekleyin.

Örneğin, şu anda okuduğunuz bu dosya https://github.com/tensorflow/docs deposundan alınmıştır. Bu nedenle, aynı depodaki diğer dosyalara şu şekilde göreceli yollarla bağlantı verebilir:

Bu, tercih edilen yaklaşımdır çünkü bu şekilde tensorflow.org , GitHub ve Colab'daki bağlantıların tümü çalışır. Ayrıca, okuyucu bir bağlantıya tıkladığında aynı sitede kalır.

Mevcut depoda bulunmayan dosyalara bağlantı vermek için, tam URI içeren standart Markdown bağlantıları kullanın. Mümkünse tensorflow.org URI'sine bağlantı vermeyi tercih edin.

Kaynak koduna bağlantı vermek için, https://www.github.com/tensorflow/tensorflow/blob/master/ ile başlayan ve GitHub kök dizininden başlayarak dosya adını içeren bir bağlantı kullanın.

tensorflow.org adresinden bağlantı verirken, "harici bağlantı" simgesinin görünmesi için Markdown bağlantısına bir `` ekleyin.

  • [GitHub](https://github.com/tensorflow/docs) GitHub'ı üretir

Bağlantıya URI sorgu parametreleri eklemeyin:

  • Kullanım: https://www.tensorflow.org/guide/data
  • Not: https://www.tensorflow.org/guide/data?hl=en

Görseller

Önceki bölümde verilen tavsiyeler sayfalara verilen bağlantılar içindir. Görseller farklı şekilde ele alınır.

Genellikle, görselleri doğrudan göndermemelisiniz; bunun yerine, çekme isteğinize TensorFlow-Docs ekibini ekleyin ve görselleri tensorflow.org adresinde barındırmalarını isteyin. Bu, deponuzun boyutunu düşük tutmanıza yardımcı olur.

Deponuza resim gönderirken, bazı sistemlerin resimlere giden göreceli yolları desteklemediğini unutmayın. Tensorflow.org adresindeki resmin nihai konumuna işaret eden tam bir URL kullanmayı tercih edin.

Site yayınlandığında API bağlantıları dönüştürülür. Bir sembolün API referans sayfasına bağlantı vermek için, sembol yolunu ters tırnak işaretleri içine alın:

Uzun yollar hariç, tam yollar biraz daha tercih edilir. Yollar, baştaki yol bileşenleri çıkarılarak kısaltılabilir. Kısmi yollar şu durumlarda bağlantıya dönüştürülecektir:

  • Yolda en az bir nokta . var ve
  • Bu kısmi yol, proje içerisinde benzersizdir.

Tensorflow.org'da yayınlanan Python API'sine sahip her proje için API yolları bağlantılıdır. API adlarını ters tırnak işaretleri içine alarak tek bir dosyadan birden fazla alt projeye kolayca bağlantı verebilirsiniz. Örneğin:

Birden fazla yol takma adına sahip semboller için, tensorflow.org adresindeki API sayfasına uyan yola hafif bir öncelik verilir. Tüm takma adlar doğru sayfaya yönlendirilecektir.

Markdown'da Matematik

Markdown dosyalarını düzenlerken TensorFlow içinde MathJax kullanabilirsiniz, ancak aşağıdaki hususlara dikkat edin:

  • MathJax, tensorflow.org adresinde düzgün bir şekilde görüntüleniyor.
  • MathJax, GitHub'da düzgün şekilde görüntülenmiyor.
  • Bu gösterim, konuya aşina olmayan geliştiriciler için caydırıcı olabilir.
  • Tutarlılık sağlamak amacıyla tensorflow.org , Jupyter/Colab ile aynı kuralları izler.

MathJax kod bloğunun etrafına $$ işareti koyun:

$$
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 \]

MathJax ifadelerini satır içi olarak $ ... $ ile çevreleyin:


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

Bu, satır içi bir MathJax ifadesinin örneğidir: \( 2 \times 2 = 4 \)

\\( ... \\) ayırıcıları satır içi matematiksel işlemler için de kullanılabilir, ancak $ biçimi bazen daha okunaklıdır.

Nesir üslubu

Eğer anlatım içeren dokümantasyonun önemli bölümlerini yazacak veya düzenleyecekseniz, lütfen Google Geliştirici Dokümantasyon Stil Kılavuzu'nu okuyun.

İyi stilin ilkeleri

  • Yazılarınızdaki imla ve dilbilgisi hatalarını kontrol edin. Çoğu editörde imla denetleyici bulunur veya imla denetleme eklentisi mevcuttur. Daha kapsamlı bir imla ve dilbilgisi denetimi için metninizi Google Dokümanlar veya diğer belge yazılımlarına da yapıştırabilirsiniz.
  • Samimi ve dostane bir üslup kullanın. TensorFlow dokümantasyonunu sanki başka bir kişiyle birebir konuşuyormuş gibi, bir sohbet havasında yazın. Makalede destekleyici bir ton kullanın.
  • Açıklamalardan, görüşlerden ve değer yargılarından kaçının. "Kolayca", "sadece" ve "basit" gibi kelimeler varsayımlarla doludur. Bir şey size kolay gelebilir, ancak başka biri için zor olabilir. Mümkün olduğunca bunlardan kaçınmaya çalışın.
  • Karmaşık jargon kullanmadan, basit ve özlü cümleler kullanın. Birleşik cümleler, yan cümle zincirleri ve yerel deyimler metni anlamayı ve çevirmeyi zorlaştırabilir. Bir cümle ikiye bölünebiliyorsa, muhtemelen bölünmelidir. Noktalı virgül kullanmaktan kaçının. Uygun olduğunda madde işaretli listeler kullanın.
  • Bağlam sağlayın. Kısaltmaları açıklama yapmadan kullanmayın. TensorFlow dışı projelerden bahsetmeden onlara bağlantı vermeyin. Kodun neden bu şekilde yazıldığını açıklayın.

Kullanım kılavuzu

Operasyonlar

Markdown dosyalarında, bir işlemin ne döndürdüğünü göstermek istediğinizde tek eşittir işareti yerine # ⇒ işaretini kullanın.

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

Not defterlerinde, yorum eklemek yerine sonucu görüntüleyin (Not defteri hücresindeki son ifade bir değişkene atanmamışsa, otomatik olarak görüntülenir.)

API referans belgelerinde sonuçları göstermek için doctest kullanılması tercih edilir.

Tensörler

Genel olarak bir tensörden bahsederken, "tensör" kelimesini büyük harfle yazmayın. Bir işleme sağlanan veya işlemden döndürülen belirli bir nesneden bahsederken, "Tensor" kelimesini büyük harfle yazmalı ve etrafına ters tırnak işaretleri koymalısınız çünkü bir Tensor nesnesinden bahsediyorsunuz.

Birden fazla Tensor nesnesini tanımlamak için "Tensors (çoğul)" kelimesini kullanmayın, gerçekten tek bir Tensors nesnesinden bahsediyorsanız bunun yerine " Tensor nesnelerinin bir listesi (veya koleksiyonu)" deyin.

Tensörün eksenlerini detaylandırmak için "şekil" kelimesini kullanın ve şekli köşeli parantezler içinde ters tırnak işaretleriyle gösterin. Örneğin:


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

Yukarıda belirtildiği gibi, bir Tensor şeklinin elemanlarından bahsederken "boyut" yerine "eksen" veya "indeks"i tercih edin. Aksi takdirde, "boyut"u bir vektör uzayının boyutuyla karıştırmak kolaydır. "Üç boyutlu bir vektörün" uzunluğu 3 olan tek bir ekseni vardır.