NextPDF belgelendirmesinin yapısı

Genel bakış

NextPDF kılavuzu sabit bir sözleşmeye uyar. Her sayfanın tek bir konusu, tek bir Diataxis kipi ve tek bir sayfa türü vardır. Her sayfa türü için zorunlu bir düzey-2 başlık kümesi bulunur. Küçük bir bildirim ve kapı kümesi, kılavuz büyüdükçe yapının tutarlı kalmasını sağlar.

Bu sayfa, katkınızı doğru şekilde yerleştirebilmeniz için bu sistemi ana hatlarıyla açıklar. Tam başlık listeleri, alıntı kuralları ve kapı bağlama yordamı dahil olmak üzere normatif sözleşmenin tamamı, iç yönetişim belgesi docs/style/expansion-standard.md içinde yer alır. Önce bu sayfayı okuyun. İçerik yazarken o belgeye başvurun.

Sayfa türü seçimi

Yeni bir sayfa mı ekleyeceğinize yoksa mevcut bir sayfayı mı genişleteceğinize karar vermek için aşağıdaki kuralları sırayla uygulayın:

1. İçerik, bir okuyucunun mevcut sayfada bulmayı beklemeyeceği ayrı bir konuysa, yeni bir sayfa ekleyin.
2. İçerik, mevcut sayfanın halihazırda sahip olduğu bir konuyu tamamlıyorsa, o sayfayı genişletin.
3. İçerik, bir kurulum, hızlı başlangıç veya görev sayfasını şişirecek derin bir ayrıntıysa, onu ayrı bir sayfaya taşıyın ve bu sayfaya bağlantı verin.
4. Aksi takdirde mevcut sayfayı genişletin.

Sayfanın var olması gerektiğine karar verdikten sonra Diataxis kipini ayarlayın. Kip, sayfa türünü belirler:

• Öğretici, öğrenme aşamasındaki okuyucuya öğretir. Tarif biçiminde yazılmış bir görev kılavuzu kullanın.
• Nasıl yapılır, yetkin bir okuyucunun bir görevi tamamlamasına yardımcı olur. Bir görev kılavuzu, bir sunucu API kılavuzu veya bir yazılım geliştirme kiti kılavuzu kullanın.
• Başvuru, kesin olguları sunar. Bir API başvurusu veya bir dizin sayfası kullanın.
• Açıklama, kavrayış kazandırır. Bir geliştirici kılavuzu veya bir premium özellik kılavuzu kullanın.

Sade dil, ayrı bir kip değil, her kip için temel ölçüttür.

Sayfa türü kataloğu

Kılavuz sözleşmesi şu türleri tanır. Sayfanız bir API tablosu içeriyorsa mevcut bir türü yeniden kullanın. Yeni bir yalnızca-etiket türünü yalnızca API tablosu olmayan bir sayfa için kullanıma sokun.

• Dizin türleri: section-index, api-index, extension-index.
• Başvuru türü: api-reference. Bunu, sunucu ve Python SDK başvuruları dahil olmak üzere standart API tablosunu içeren herhangi bir sayfa için yeniden kullanın.
• Açıklama türü: developer-guide. Bunu, sunucu ve Python SDK kılavuzları dahil olmak üzere mimari, yaşam döngüsü ve uzantı noktası içeriği için yeniden kullanın.
• Yeni yalnızca-etiket türleri: premium-feature-guide ve task-guide; her ikisi de API tablosu olmayan sayfalar içindir.

Her sayfa ## At a glance ile başlar. Her api-reference sayfası, ortak API tablosunu ve Development notes başlığını içerir. Zorunlu başlıklar düzey-2 başlık olarak kullanılır ve her biri kendi satırında yer alır. Bunların altına başka başlıklar ekleyebilirsiniz.

İçerik yazma denetim listesi

Bir sayfa yazarken her iki denetim listesini de yerine getirin. İç standart, her maddeyi normatif olarak belirtir ve onu destekleyen standarda bağlantı verir.

Geliştirici dostluğu:

• Çalıştırılabilir örnekleri examples/ veya tests/Cookbook kaynağından alın ve çitle çevrilmiş her bloğa bir title= bilgi dizesi verin.
• Ön koşulları hem ön bilgi alanında hem de giriş bölümünde belirtin.
• Çıktı üreten her örnek için beklenen çıktıyı gösterin.
• Blokları kopyalanıp yapıştırılmaya hazır tutun: blok başına tek bir dil, ilk kullanımda tam adlar ve sonunda komut istemi karakteri olmadan.
• Varsayılan olarak güvenli kod gösterin: üretim örnekleri en özgül NextPDF istisnasını kullanarak try/catch uygular ve hiçbir zaman boş bir catch kullanmaz.
• İleriye dönük bağlantılarla bitirin ve ön bilgi alanındaki related: değerini ayarlayın.

Çeviriye hazırlık:

• Makine çevirisindeki belirsizliği sınırlamak için her cümlede tek bir düşünce yazın.
• Çoğu hedef dil metni uzattığı için başlıkları ve etiketleri kısa tutun.
• Deyimlerden kaçının.
• Simge adlarını, yapılandırma anahtarlarını, CLI bayraklarını ve istisna adlarını kod biçimlendirmesinde tutun; PDF/A-4, PAdES ve eIDAS gibi standart adları hiçbir zaman çevirmeyin.
• Hem i18n_ready hem de xliff_segments değerlerini dürüstçe ayarlayın ve Unicode NFC ile yazın.

Üslup, kod örneği, terminoloji ve alıntı biçimi için iç standardın atıfta bulunduğu onaylanmış üslup geçersiz kılma sayfasını izleyin.

Kapı bağlama

Yeni bir sayfayı aşağıdaki sıralı yordamla bağlayın:

1. Sayfanın iskeletini, ön bilgi alanı site şemasıyla eşleşecek şekilde oluşturun.
2. Gövdeyi, sayfa türünün zorunlu başlıklarına göre yazın.
3. Şu { path, owner, kind, headings[] } girdisini docs/manual-contract.json dosyasına ekleyin. Yol, src/content/docs konumuna görelidir, ileri eğik çizgi kullanır, başında eğik çizgi bulunmaz ve .. içermez.
4. Bir API başvurusu için, sayfanın simgelerini docs/api-coverage-manifest.json dosyasına ekleyin; her simge sayfada görünmeli ve kaynakta bulunmalıdır.
5. Sadece sayfa yeni bir kaynak deposundan geldiğinde docs/source-manifest.json dosyasını güncelleyin.
6. Sayfayı astro.config.mjs içindeki doğru kenar çubuğu grubuna açık bir girdi olarak ekleyin.
7. Yalnızca İngilizce bir sayfa için on yedi yerel ayar hücresinin tamamı missing olarak ayarlanmış bir yerel ayar kapsamı satırı ekleyin.
8. Belgelendirme kapılarını, derlemeyi ve başarım bütçesini çalıştırın.

Site sahipliğindeki sayfalar src/content/docs altında yer alır, owner değerini nextpdf-docs olarak ayarlar ve hiçbir zaman bir toplama işaretçisi taşımaz. Toplanmış sayfalar bir kaynak deposundan gelir. Bu sayfaların yayımlama bayrağı kaynak ön bilgi alanında yer alır; bu nedenle onları burada değil, orada düzenleyin.

Ayrıca bakınız

• Tümleştirmeler: birçok pakete yayılan kılavuz yapısının en kapsamlı işlenmiş örneği.
• İç yönetişim belgesi docs/style/expansion-standard.md sözleşmenin tamamını içerir: her sayfa türü için tam başlık listeleri, alıntı kuralları ve eksiksiz kapı bağlama yordamı.