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
```
Markdown ve not defterlerindeki bağlantılar
Depodaki dosyalar arasındaki bağlantılar
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:
-
[Basics](../../guide/basics.ipynb)
Temel Bilgiler'i üretir.
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.
Dış bağlantılar
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 belgelerine bağlantılar
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:
-
`tf.data.Dataset`
tf.data.Dataset
üretir
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:
-
`tf.metrics`
,`tf_agents.metrics`
,`text.metrics`
şunu üretir:tf.metrics
,tf_agents.metrics
,text.metrics
.
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.