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 Developer Dokümanlar Stil Kılavuzu yararlıdır.

indirim

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

Kod hakkında yaz

Kodun satır içi sözleri

Metinde kullanıldığında aşağıdaki sembollerin çevresine `backticks` koyun:

  • Argüman adları: `input` " , "x" , `tensor` `x`
  • Döndürülen tensör adları: `output` ", `idx` ", "out `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 tepme kullanın. İsteğe bağlı olarak, ilk backtick grubundan sonra programlama dilini belirtin, örneğin:


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

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

Örneğin, okuduğunuz bu dosya https://github.com/tensorflow/docs deposundan. Bu nedenle, aynı depodaki diğer dosyalara aşağıdaki gibi bağlanmak için göreli yolları kullanabilir:

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

Geçerli depoda olmayan dosyalara bağlantılar için, tam URI ile standart Markdown bağlantılarını kullanın. Varsa, tensorflow.org URI'sine bağlantı vermeyi tercih edin.

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

tensorflow.org'dan bağlantı kurarken, "harici bağlantı" sembolünün gösterilmesi için Markdown bağlantısına bir {:.external} .

  • [ GitHub [GitHub](https://github.com/tensorflow/docs){:.external} üretir

URI sorgu parametrelerini bağlantıya dahil etmeyin:

  • Kullanın: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Not: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Görüntüler

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

Genel olarak, görüntüleri iade etmemelisiniz ve bunun yerine TensorFlow-Docs ekibini PR'nize eklemeli ve onlardan görüntüleri tensorflow.org'da barındırmalarını istemeniz gerekir. Bu, deponuzun boyutunu düşük tutmaya yardımcı olur.

Deponuza görsel gönderirseniz, bazı sistemlerin görsellere giden bağıl yolları işlemediğini unutmayın. Tensorflow.org'da görüntünün nihai konumuna işaret eden tam bir URL 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ğlanmak için sembol yolunu ters tik işareti içine alın:

Uzun yollar dışında tam yollar biraz tercih edilir. Yollar, önde gelen yol bileşenleri bırakılarak kısaltılabilir. Kısmi yollar şu durumlarda bağlantılara dönüştürülür:

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

API yolları, tensorflow.org'da yayınlanan bir Python API'si ile her proje için bağlantılıdır. API adlarını ters tiklerle sararak tek bir dosyadan birden çok alt projeye kolayca bağlanabilirsiniz. Örneğin:

Birden çok yol takma adı olan semboller için, tensorflow.org'daki API sayfasıyla eşleşen yol için küçük bir tercih vardır. 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ğıdakilere dikkat edin:

  • MathJax, tensorflow.org'da düzgün bir şekilde işleniyor.
  • MathJax, GitHub'da düzgün şekilde oluşturulmuyor.
  • Bu gösterim, tanıdık olmayan geliştiriciler için rahatsız edici olabilir.
  • Tutarlılık için tensorflow.org , Jupyter/Colab ile aynı kuralları izler.

Bir 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ı tarzı

Anlatı belgelerinin önemli bölümlerini yazacak veya düzenleyecekseniz, lütfen Google Developer Documentation Style Guide'ı okuyun.

İyi stil ilkeleri

  • Katkılarınızda yazım ve dil bilgisini kontrol edin. Çoğu düzenleyicide bir yazım denetleyicisi bulunur veya mevcut 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 belge yazılımına da yapıştırabilirsiniz.
  • Sıradan ve arkadaşça bir ses kullanın. TensorFlow belgelerini bir konuşma gibi yazın; sanki başka bir kişiyle bire bir konuşuyormuşsunuz gibi. 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 yüklüdür. Bir şey size kolay gelebilir, ancak başka biri için zor olabilir. Mümkün olduğunda bunlardan kaçınmaya çalışın.
  • Karmaşık jargon olmadan basit, özlü cümleler kullanın. Birleşik cümleler, cümle zincirleri ve konuma özgü deyimler metnin anlaşılmasını ve çevrilmesini zorlaştırabilir. Bir cümle ikiye bölünebiliyorsa, muhtemelen olmalıdır. Noktalı virgüllerden 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, bunlara bağlantı vermeden bahsetmeyin. Kodun neden bu şekilde yazıldığını açıklayın.

kullanım kılavuzu

Operasyonlar

İşaretleme 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 (Bir 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 kullanmayı tercih eder.

Tensörler

Genel olarak bir tensör hakkında konuşurken, tensör kelimesini büyük harfle yazmayın. Bir operasyona sağlanan veya bir operasyondan döndürülen belirli nesne hakkında konuşurken, o zaman bir Tensor nesnesinden bahsettiğiniz için Tensor kelimesini büyük harfle yazmalı ve etrafına ters tik eklemelisiniz.

Gerçekten bir Tensors nesnesinden Tensors , birden fazla Tensor nesnesini tanımlamak için Tensör (ç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 tiklerle 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" tercih edin. Aksi takdirde, "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.