Ana içeriğe geç

Dokümantasyon stil kılavuzu

Bu kılavuz, yeni içerik yazma ve mevcut içeriği çevirme ile ilgili olarak beklenen stil, MkDocs'a özgü sözdizimi, çeşitli gerekli araçlar ve dokümantasyon çevirisi hakkında bilgiler içerir.

Genel stil

  • Başlıklar ve başlıkların sadece ilk kelimesi büyük harfle yazılmalıdır.
  • Programlamaya özgü konuşma dilinde kullanılan bazı kelimeler (örneğin, "apps") ve isimlerin fiil olarak kullanılması (örneğin, "scrollable") dışında, ABD İngilizcesi yazım kurallarını tercih ediyoruz.
  • "Artefact" ve "artefacts" kelimelerinin yazımı gösterildiği gibidir.
  • Nokta işaretinden sonra tek boşluk kullanıyoruz.
  • Boşluklarla çevrili tek bir tireyi uzun tire (veya HTML — literal) olarak kullanıyoruz.
  • Ürün adına yapılan her türlü atıfta, ürünün tercih edilen büyük harf kullanımı kullanılmalıdır. (ör. "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • Bir terim "kod olarak" kullanılıyorsa, sözlüğe eklenmek yerine tekli ters eğik çizgi ile çevrelenerek satır içi kod olarak alıntılanmalıdır.
  • Kullanıcının yapması gereken eylemleri açıklarken "basitçe", "sadece" veya "kolayca" gibi terimleri kullanmaktan kaçınırız. Bu terimler, özellikle kullanıcı zorluklarla karşılaştığında, aşağılayıcı olarak algılanabilir.

Çapraz referans bilgileri

Mümkün olduğunda belgelerdeki içeriği çapraz referanslamalısınız. Bu bölümde, referans verilen bilginin türüne göre bunu yapabileceğiniz çeşitli yöntemler ele alınmaktadır.

MkDocs, standart Markdown biçimli bağlantıları görüntüler. Standart Markdown biçimli web hiper bağlantıları aşağıdaki gibidir:

[Link text](https://example.com/)

Bu biçimi yerel bir dosyaya bağlantı vermek için de kullanabilirsiniz:

[Link text](path/to/file.md)

Dosyaların belirli bölümlerine veya API belgelerine referans vermek için MkDocs referans bağlantı formatını kullanmanız gerekir.

Özel Markdown bağlantıları ve içerik çapraz referansları

Markdown, başlığın içeriğine göre tüm başlıklar için (bir satırda bir ila altı # sembolüyle başlayan her şey) bağlantılar oluşturur. Örneğin, bu bölüm için oluşturulan bağlantı custom-markdown-anchors-and-content-cross---referencing şeklindedir. Ancak, çevirilerimizin çalışma şekli nedeniyle, bir bölüm başlığına her atıfta bulunulduğunda, bu başlığın özel bir bağlantısı olmalıdır.

MkDocs, değiştirilmiş Markdown bağlantısı kullanarak belgedeki çeşitli diğer öğelere bağlantı vermenizi sağlayan bir referans bağlantı sözdiziminin oluşturulmasını destekler. Bu, diğer şeylerin yanı sıra, özel Markdown başlıklarına ve metin bağlantılarına bağlantı vermeyi de içerir.

MkDocs referans bağlantıları, aşağıdaki şekilde biçimlendirilmiş tüm bağlantılardır:

[Link text][link-target]

Özel başlık ve içerik bağlantıları gereklidir

BeeWare belgelerinde MkDocs referans bağlantısı aracılığıyla metin içeriğinde referans verilen herhangi bir başlık veya içerik bölümüne özel bir bağlantı eklenmelidir. Aksi takdirde, başlık içeriği çevrildiğinde bağlantılar bozulabilir.

Bir başlık bağlantısına bağlanmanız gerekiyorsa, amaçlanan içerik için özel bir bağlantı oluşturmanız gerekir. Özel bir bağlantı ayarlamak için genel sözdizimi aşağıdaki gibidir:

# Header text { #anchor-name }

Örneğin, bu bölümün bağlantısını custom-anchors olarak özelleştirmek için aşağıdaki biçimlendirme kullanılır:

## Custom Markdown anchors { #custom-anchors }

Metin ve kod blokları dahil genel içerik üzerinde de bağlantı oluşturabilirsiniz. Bağlantı vermek istediğiniz içeriğin üzerine, üstünde ve altında satır sonu bulunan aşağıdaki biçimlendirme eklenmelidir:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Özel bağlantı noktaları oluşturulduktan sonra, aynı belge içinden veya belgenin diğer bölümlerinden bu bağlantı noktalarına bağlantı verebilirsiniz.

Standart Markdown, aynı dosya içindeki bir bağlantıya bağlanmak için kullanılır ve şu şekilde biçimlendirilir:

[Link text](#anchor-name)

Ayrı bir belgedeki bir bağlantıya bağlanmak için MkDocs referans bağlantı stili kullanılır. Bu stil aşağıdaki şekilde biçimlendirilir:

[Link text][anchor-name]

API referans bağlantıları

MkDocs referans bağlantısı, belgelenmiş sınıflar, sınıf yöntemleri veya öznitelikler ve belirli harici belgeleme referansları dahil olmak üzere API belgelerinin çapraz referanslamasını da destekler.

Aynı dosyadan veya ayrı bir dosyadan bağlantı kurduğunuzdan bağımsız olarak, belgelenmiş bir sınıfa, sınıf yöntemine veya özniteliğine bağlantı kurmak için birden fazla seçenek vardır. Sınıflara vb. bağlantı kurarken, adı satır içi kod olarak görüntülemek için ilk köşeli parantez setine ters eğik çizgi eklemelisiniz. Ters eğik çizgiler, satır içi kod olarak görüntülenmemesi gereken özel metin kullanıyorsanız gerekli değildir. İkinci köşeli parantez setine asla ters eğik çizgi eklenmemelidir.

Ad alanını görüntülerken bir sınıfa bağlantı vermek aşağıdaki şekilde biçimlendirilir:

[`module.ClassName`][]

Sadece sınıf adını gösterirken bir sınıfa bağlantı vermek aşağıdaki şekilde biçimlendirilir:

[`ClassName`][module.ClassName]

Özellikler yukarıdakilerle aynıdır, ancak özellik adı da eklenmiştir. Aşağıda ad alanı gösterilmektedir:

[`module.ClassName.attributename`][]

Sınıflar gibi, yalnızca öznitelik adının görüntülenmesi aşağıdaki gibi biçimlendirilir:

[`attributename`][module.ClassName.attributename]

Yöntemler, ad alanının ardından () ile gösterilmelidir ve bu nedenle özniteliklerden farklı şekilde ele alınmalıdır. Aşağıda, bir yönteme bağlantı vermenin uygun yolu gösterilmektedir:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Aşağıda sadece sınıf ve yöntem adı gösterilmektedir. Bu, adın arkasına parantez eklemeyi de gerektirir:

[`Classname.methodname()`][module.Classname.methodname]

Uygulanabilir ad alanı ile aynı yöntemi kullanarak, rastgele metin görüntülerken bir sınıfa, yönteme veya özniteliğe bağlantı verebilirsiniz. Bunu bir sınıfla yapmak için aşağıdaki biçim kullanılır:

[link text][module.ClassName]

Python çekirdek belgelerine ve Pillow belgelerine doğrudan bağlantı vermek de mümkündür. Örneğin, int belgelerine bağlantı vermek için:

[`int`][]

Pillow Image belgelerine bağlantı vermek için:

[`PIL.Image.Image`][]

Kod bloğu ipuçları

Dil ve kod vurgulaması

Kod bloğu içindeki kodun dilini, ilk üç ters eğik çizginin ardından boşluk bırakmadan dil adını ekleyerek belirtebilirsiniz. Bu, kod görüntülendiğinde uygun kod vurgulaması ile sonuçlanır. Örneğin, Python'u belirtmek için kod bloğunu ```python ile başlatmanız gerekir.

Konsol komutları ve kopyala düğmesi

Konsol komutları veya çıktı içeren komutlar ekliyorsanız, Unix benzeri (macOS dahil) işletim sistemini mi yoksa Windows'u mu tanımladığınıza bağlı olarak, bunları console veya doscon olarak etiketleyin. İşletim sistemi tarafından sağlanan komut istemini ekleyebilirsiniz; kopyala düğmesine tıklandığında yalnızca komut kopyalanır. Örneğin, bir kod bloğunu ```console ile başlatır ve aşağıdaki içeriği eklerseniz:

$ mkdir test
$ ls
test

Ardından, kod bloğundaki kopyala düğmesine tıklandığında yalnızca komutlar kopyalanır, komut istemi ve çıktı ise yok sayılır. Bu, bunların konsol komutları olduğunu belirtmenizi sağlarken, kullanıcıların kopyala düğmesini etkili bir şekilde kullanmaya devam etmelerini sağlar.

Belirli kod satırlarını vurgulamak

Belirli kod satırlarını vurgulayabilirsiniz. Örneğin, 2. satırı vurgulamak için dilin arkasına bir boşluk ekleyip ardından {hl_lines="2"} ekleyin. Böylece kod bloğunuz ```python {hl_lines="2"} ile başlayacaktır. Sonuç şöyledir:

import toga
from toga.style.pack import COLUMN, ROW

Birden fazla farklı satırı vurgulayabilirsiniz. Örneğin, python {hl_lines="3 5 9"} 3, 5 ve 9. satırları vurgular. Bir satır aralığını da vurgulayabilirsiniz. Örneğin, python {hl_lines="3-8"} 3 ile 8. satırları vurgular. Birden fazla aralığı, örneğin python {hl_lines="9-18 23-44"} ile vurgulayabilirsiniz.

Özel biçimlendirme gerektiren Markdown öğeleri

Çeviri dosyalarının oluşturulma şekli nedeniyle, uyarılar, notlar, sekmeler, Jinja yönergeleri, resim başlıkları ve hizalama vb. için Markdown sözdiziminde gerekli satır sonlarını eklemek önemlidir.

Uyarılar ve notlar

Uyarılarda, uyarı başlangıcı ve bitişinden önce ve sonra yeni satır eklenmesi dahil olmak üzere, aşağıdaki şekilde biçimlendirme yapılmalıdır:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Bu, desteklenen tüm uyarı türleri için aynı şekilde çalışır. Örneğin, not uyarıları da aynı biçimlendirme ve satır sonlarını gerektirir:

Content above.

/// note | Note title

Note text here.

///

Content below.

Tüm desteklenen uyarı türleri uyarı olarak kullanılabilir.

Sekmeli içerik

Sekmeli içerik, içerik bloğunun başlangıcından önce ve sonundan sonra yeni bir satır eklenerek aşağıdaki şekilde biçimlendirilir:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

İç içe geçmiş bir uyarı içeren sekme, içerik bloğunun öncesinde ve sonrasında yeni satır dahil olmak üzere aşağıdaki şekilde biçimlendirilir:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Çökmüş içerik

Çökmüş içerik, satır sonları dahil olmak üzere aşağıdaki şekilde biçimlendirilir:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Tüm desteklenen uyarı türleri daraltılmış içerikle kullanılabilir, ancak bunları details-admonitiontype olarak beyan etmeniz gerekir. Dolayısıyla, "not" türü daraltılmış blok details-note (yukarıda gösterildiği gibi), "uyarı" türü daraltılmış blok details-warning vb. olacaktır.

Jinja yönergeleri

Belgelerin metninde Jinja yönergelerini kullanan birkaç özellik vardır. Jinja yönerge özelliklerini kullanan her şey yeni satırlarla sarılmalıdır. Örneğin, BeeWare öğreticisi ana sayfada hangi uyarıyı göstereceğini belirlemek için değişkenlere dayalı Jinja koşulları içerir. Bunlar aşağıdaki gibi biçimlendirilmiştir:

Content above.



Content below.

Sembolleri veya metni değiştirmek için bir sözdizimi de vardır. Bu sözdizimi, bir çift eşleşen çift kıvrımlı parantez içine alınmış bir değişkendir ve kendi satırında ise, öncesinde ve sonrasında yeni satır içermelidir.

Content above.

{{ variable }}

Content below.

Görüntü biçimlendirme

Görüntülerin genişliği ayarlanabilir ve sol, sağ ve ortaya hizalanabilir (ortaya hizalama konusunda bir uyarı vardır). Görüntüler, erişilebilirlik amacıyla her zaman anlamlı alternatif metinler içermelidir.

Bir görüntünün genişliğini 300px olarak ayarlamak için aşağıdaki gibi biçimlendirilir:

![Image alt text](../path/to/image.png){ width="300px" }

Bir görüntüyü sola (veya sağa) hizalamak için aşağıdaki biçimlendirme kullanılır:

![Image alt text](../path/to/image.png){ align=left }

Bir resme başlık eklemek için, başlığın öncesinde ve sonrasında yeni satır eklenmesi gerekir ve şu şekilde biçimlendirilir:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Görüntü merkezini hizalamak align özniteliği ile mümkün değildir. Çözüm, görüntünün ardından boş bir başlık eklemektir, böylece görüntü ortalanacaktır. Her bölümün arasına ve öncesine ve sonrasına satır sonu eklemeniz gerekir. Biçimlendirme şu şekildedir:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Özel Markdown biçimlendirmesine sahip eklentiler

Aşağıdaki bölümlerde, belirli Markdown biçimlendirme gerektiren eklentilerin nasıl kullanılacağı anlatılmaktadır.

Snippet'leri kullanarak harici içerik ekleme

Yerel bir dosyadan veya URL'den harici içeriği eklemeyle ilgili ayrıntılar için Snippets uzantısı belgelerine bakın. Snippets, belge yürütülmesi gereken Jinja yönergeleri içermediği sürece kullanılmalıdır (Jinja yürütme, Snippets işlemeyle birlikte gerçekleşir ve bu nedenle dosyadaki Jinja işlenmez). Snippets, bir dosyanın belirli bölümlerini ayrı ayrı eklemenizi sağlayan sınırlayıcılar kullanmak istiyorsanız gereklidir, örneğin kaynak belge birbirinden ayrı olarak eklenecek bölümlere ayrılmıştır.

Önemli notlar:

  • Snippet tanımlayıcı olarak -8<- kullanıyoruz. Belgelerde birkaç seçenek gösterilmektedir; lütfen bizim stilimizi takip edin.
  • BeeWare Docs Tools paylaşılan içeriğinde bulunan dosyalar "yerel" içerik olarak değerlendirilir. Bu nedenle, ya -8<- "docs-style-guide.md" gibi sadece dosya adını kullanacaksınız ya da içerik bir alt dizindeyse, -8<- "style/docs-style-guide.md" gibi sadece dizin ve dosya adını kullanacaksınız.
  • GitHub'daki bir dosyadan URL aracılığıyla harici içerik ekliyorsanız, ham içerik URL'sini kullanmanız gerekir, aksi takdirde eklediğiniz yere tam web sayfası gömülür.

BeeWare Docs Tools paylaşılan içeriğinden içerik eklemek için Makrolar kullanma

Macros MkDocs eklentisi kullanarak BeeWare Docs araçlarının paylaşılan içerik dizininden içerik ekleyebilirsiniz. Bu yöntem, belge içinde yürütülmesi gereken Jinja yönergeleri varsa gereklidir ve yalnızca bu durumda kullanılmalıdır. URL aracılığıyla harici içerikle çalışmaz. Macros değişken değiştirme mekanizması bu yöntemle çalışır.

Makroları kullanarak içerik eklemek için çeşitli seçenekler mevcuttur:

  1. Belgeyi başka hiçbir manuel değişiklik yapmadan eklemek istiyorsanız include Jinja sözdizimi kullanın.

  2. Belgeye Jinja extends sözdizimini eklediyseniz, belirli bölümleri geçersiz kılmak veya bunlara ekleme yapmak için [(https://jinja.palletsprojects.com/en/stable/templates/#child-template) Jinja sözdizimini]block kullanın.

pyspelling

pyspelling yazım denetleyicisini kullanıyoruz. Bu, lint denetimleri sırasında çalıştırılır.

pyspelling yanlış yazılmış bir kelimeyi belirlediğinde, çoğu durumda bu kelime dokümantasyon içeriğinde düzeltilmelidir.

Nadiren, pyspelling sözlüğünde bulunmayan geçerli bir kelime tespit edilmesi durumunda, iki seçeneğiniz vardır:

  1. Bir kelime birden fazla kez tekrar kullanılma olasılığı yüksekse, bu kelimeyi spelling_wordlist dizinindeki docs belgesine alfabetik sırayla eklemelisiniz.
  2. Tekrar kullanılma olasılığı düşük bir kelimeyse, onu <nospell> / </nospell> etiketiyle sarabilirsiniz ve pyspelling onu satır içinde yok sayacaktır.