TensorFlow dokümantasyon stili kılavuzu

En iyi uygulamalar

  • Kullanıcı amacına ve hedef kitleye odaklanın.
  • Günlük kelimeleri kullanın ve cümleleri kısa tutun.
  • Tutarlı cümle yapısı, ifadeler ve büyük harf kullanımı kullanın.
  • Dokümanlarınızın taranmasını kolaylaştırmak için başlıkları ve listeleri kullanın.
  • Google Geliştirici Dokümanları Stil Kılavuzu faydalıdır.

İndirim

Birkaç istisna dışında TensorFlow, GitHub Flavored Markdown'a (GFM) benzer bir Markdown sözdizimi kullanır. Bu bölümde GFM Markdown sözdizimi ile TensorFlow belgeleri için kullanılan Markdown arasındaki farklar açıklanmaktadır.

Kod hakkında yazın

Koddan satır içi bahsetmeler

Metinde kullanıldığında aşağıdaki simgelerin etrafına `backticks` koyun:

  • Bağımsız değişken adları: `input` , `x` , `tensor`
  • Döndürülen tensör adları: `output` , `idx` , `out`
  • Veri türleri: `int32` , `float` , `uint8`
  • Metindeki diğer işlem adları referansı: `list_diff()` , `shuffle()`
  • Sınıf adları: `tf.Tensor` , `Strategy`
  • Dosya adı: `image_ops.py` , `/path_to_dir/file_name`
  • Matematik ifadeleri veya koşulları: `-1-input.dims() <= dim <= input.dims()`

Kod blokları

Bir kod bloğunu açmak ve kapatmak için üç geri tıklama kullanın. İsteğe bağlı olarak, ilk geri tıklama grubundan sonra programlama dilini belirtin, örneğin:


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

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

Örneğin okuduğunuz bu dosya https://github.com/tensorflow/docs deposundandır. Bu nedenle, aynı depodaki diğer dosyalara bağlanmak için göreceli yolları şu şekilde kullanabilir:

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

Geçerli depoda bulunmayan dosyalara bağlantılar için tam URI'ye sahip standart Markdown bağlantılarını kullanın. Varsa tensorflow.org URI'sine bağlanmayı tercih edin.

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

tensorflow.org'a bağlantı verirken, "harici bağlantı" sembolünün gösterilmesi için Markdown bağlantısına bir `` ekleyin.

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

Bağlantıya URI sorgu parametrelerini dahil etmeyin:

  • Şunu kullanın: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Değil: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Görseller

Önceki bölümdeki tavsiye sayfalara bağlantılar içindir. Görüntüler farklı şekilde işlenir.

Genel olarak görselleri teslim etmemeli, bunun yerine TensorFlow-Docs ekibini PR'nize eklemeli ve onlardan görselleri tensorflow.org'da barındırmalarını istemelisiniz. Bu, deponuzun boyutunu küçük tutmanıza yardımcı olur.

Deponuza görseller gönderirseniz bazı sistemlerin görsellere giden göreceli yolları işlemediğini unutmayın. Tensorflow.org'da görüntünün nihai konumunu gösteren tam URL'yi kullanmayı tercih edin.

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

Uzun yollar dışında tam yollar biraz tercih edilir. Yollar, baştaki yol bileşenleri bırakılarak kısaltılabilir. Aşağıdaki durumlarda kısmi yollar bağlantılara dönüştürülecektir:

  • En az bir tane var . yolda ve
  • Kısmi yol proje içerisinde benzersizdir.

API yolları her proje için tensorflow.org'da yayınlanan bir Python API'sine bağlanır. API adlarını geri işaretlerle sararak tek bir dosyadan birden çok alt projeye kolayca bağlantı oluşturabilirsiniz. Örneğin:

Birden fazla yol takma adı olan semboller için, tensorflow.org'daki API sayfasıyla eşleşen yol için hafif bir tercih vardır. Tüm takma adlar doğru sayfaya yönlendirilecektir.

Markdown'da Matematik

Markdown dosyalarını düzenlerken TensorFlow'da MathJax'i kullanabilirsiniz ancak aşağıdakilere dikkat edin:

  • MathJax tensorflow.org'da düzgün bir şekilde işleniyor.
  • MathJax GitHub'da düzgün şekilde işlenmiyor.
  • Bu gösterim yabancı geliştiricilere itici gelebilir.
  • Tutarlılık açısından tensorflow.org, Jupyter/Colab ile aynı kuralları izler.

MathJax bloğunun etrafında $$ kullanın:

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

Satır içi MathJax ifadelerini $ ... $ ile sarın:


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

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

\\( ... \\) sınırlayıcılar satır içi matematik için de çalışır, ancak $ formu bazen daha okunabilirdir.

Düzyazı stili

Açıklama dokümantasyonunun önemli bölümlerini yazacak veya düzenleyecekseniz lütfen Google Geliştirici Dokümantasyon Stil Kılavuzu'nu okuyun.

İyi stilin ilkeleri

  • Katkılarınızda yazım ve dilbilgisini kontrol edin. Çoğu düzenleyicide bir yazım denetleyici bulunur veya kullanılabilir bir yazım denetimi eklentisi bulunur. Daha sağlam bir yazım ve dil bilgisi denetimi için metninizi bir Google Dokümanına veya başka bir doküman yazılımına da yapıştırabilirsiniz.
  • Rahat ve samimi bir ses tonu kullanın. TensorFlow belgelerini sanki başka bir kişiyle birebir konuşuyormuşsunuz gibi bir sohbet gibi yazın. Makalede destekleyici bir ton kullanın.
  • Sorumluluk reddi beyanlarından, 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 ama başkası için zor olabilir. Mümkün olduğunca bunlardan kaçınmaya çalışın.
  • Karmaşık jargon olmadan basit, konuya odaklı cümleler kullanın. Bileşik cümleler, cümle zincirleri ve yere özgü deyimler metnin anlaşılmasını ve çevrilmesini zorlaştırabilir. Bir cümle ikiye bölünebiliyorsa muhtemelen bölünmelidir. Noktalı virgülden kaçının. Uygun olduğunda madde işaretli listeleri kullanın.
  • Bağlam sağlayın. Kısaltmaları açıklamadan kullanmayın. TensorFlow dışı projelerden onlara bağlantı vermeden bahsetmeyin. 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 bir eşittir işareti yerine # ⇒ 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ında dokümanlar, sonuçları göstermek için doctest'i kullanmayı tercih eder.

Tensörler

Genel olarak bir tensörden bahsederken tensör kelimesini büyük harfle yazmayın. Bir op'a sağlanan veya bir operasyondan döndürülen belirli bir nesneden bahsederken, bir Tensor nesnesinden bahsettiğiniz için Tensor kelimesini büyük harfle yazmalı ve etrafına geri işaretler eklemelisiniz.

Gerçekten bir Tensors nesnesinden bahsetmediğiniz sürece, birden fazla Tensor nesnesini tanımlamak için Tensors (çoğul) kelimesini kullanmayın. Bunun yerine " Tensor nesnelerinin bir listesi (veya koleksiyonu)" deyin.

Bir tensörün eksenlerini detaylandırmak için şekil kelimesini kullanın ve şekli köşeli parantez içinde ters işaretlerle 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ıdaki gibi, bir Tensor şeklinin öğeleri hakkında konuşurken "boyut" yerine "eksen" veya "indeks"i tercih edin. Aksi halde "boyut"u bir vektör uzayının boyutuyla karıştırmak kolaydır. Bir "üç boyutlu vektör" uzunluğu 3 olan tek bir eksene sahiptir.