Projenizin dokümanlarından en iyi şekilde yararlanın; çekici, kapsamlı HTML dokümantasyonu oluşturmak için Sphinx'i kullanın.

Sphinx, belge oluşturmak için en popüler araçlardan biridir. Python topluluğu genelinde, geliştiriciler bu ücretsiz ve açık kaynaklı yazılımı kullanır. Metni doğrudan kodunuzdan veya işaretleme dosyalarınızdan çıkarabilir ve ardından düz metin, HTML, PDF ve EPUB gibi çeşitli biçimlerde belgeler oluşturmak için kullanabilir.

Sfenks Kurulumu

Sphinx'i kurmadan önce, ne yaptığına ve bazı temel özelliklerine bir göz atın.

Sfenks Nedir ve Ne İşe Yarar?

Belirtildiği gibi, Sphinx bir dokümantasyon üreticisidir. Varsayılan olarak, reStructuredText (RST) biçimlendirme dilini kullanır, ancak üçüncü taraf uzantılar aracılığıyla da popüler düz metin biçimlendirme dili olan Markdown'ı kullanın. Daha sonra bu RST veya işaretleme dosyalarını HTML, PDF, kılavuz sayfaları veya tercih ettiğiniz diğer biçimlere dönüştürür.

Sphinx'in içerdiği özelliklerden bazıları şunlardır:

  • Koddan belge oluşturma yeteneği.
    • instagram viewer
  • İşlevler, sınıflar, alıntılar ve sözlük terimleri için otomatik bağlantılar kullanarak farklı belge sayfalarına çapraz referans verme yeteneği.
  • Kod blokları için sözdizimi vurgulama.
  • Dokümanların görünümünü ve verdiği hissi değiştirebilecek temalar için destek.
  • İçindekiler tablosu aracılığıyla belge ağacının kolay tanımlanması.
  • Dokümanlara kod parçacıklarının test edilmesi gibi daha fazla işlevsellik eklemek için üçüncü taraf uzantılarla entegre olabilme.

Sphinx Kurulumu

Sphinx'i kurmadan önce, sahip olduğunuzdan emin olun. Geliştirme ortamınızda yüklü Python 3. Ardından, terminalinizde aşağıdaki komutu çalıştırarak Sphinx'i kurmak için pip paket yöneticisini kullanabilirsiniz:

pip kurulum sfenks

Bu, Sphinx'i ve bağımlılıklarını indirip yükleyecektir.

Kurulumdan sonra, komut isteminde aşağıdakini çalıştırın.

sphinx-build --version

Her şey yolunda gittiyse, az önce kurduğunuz Sphinx paketinin sürüm numarasını görmelisiniz.

Yeni Bir Sfenks Projesi Oluşturma

Sphinx'i yükledikten sonra, çalışma dizininize gidin ve yeni bir Sphinx projesi oluşturmak için sphinx-quickstart komutunu çalıştırın.

sfenks-hızlı başlangıç

Bu komut, Sphinx projenizi nasıl yapılandıracağınızla ilgili bir dizi soruyu yanıtlamanızı isteyecektir. Proje adını belirtebilir ve diğer sorular için varsayılan seçenekleri kullanabilirsiniz. Gelecekte, yanıtları projenize göre özelleştirmek isteyebilirsiniz.

Dizininizin içeriğini listelerseniz, bu komutun sizin için bazı dosyalar oluşturduğunu göreceksiniz. conf.py, yapılandırma değerlerini içerir ve index.rst, belgelerinizin karşılama sayfası olarak işlev görür. Oluşturma dizini, oluşturulan belgeleri barındırır ve Sphinx, belgeleri oluşturmak için bir Makefile (Windows'ta make.bat) kullanır.

Sfenks Kullanarak Belge Yazma

Dizininizin kök dizinindeki index.rst dosyası, uygulamanızın ana sayfasıdır. Bu nedenle, VS Code gibi bir metin düzenleyiciyle açın veya başka herhangi bir iyi, ücretsiz kod düzenleyici—düzenlemek için.

index.rst'yi uygun gördüğünüz gibi değiştirebilirsiniz, ancak en azından sahip olması gereken bir şey kök toctree (içindekiler ağacı) yönergesidir. Birden çok dosyayı tek bir belge hiyerarşisine bağladığı için bu çok önemlidir.

index.rst dosyasına belge eklemek için RST işaretlemesini kullanabilirsiniz.

Örnek olarak, math_utils modülü için bir index.rst dosyası düşünün. Bu dosya, modülün amacına ilişkin kısa bir genel bakış ve belgelerin diğer sayfalarına bağlanan bir içindekiler tablosu içerebilir.

Math Utils'e hoş geldiniz
.. toctree::
 :maksimum derinlik: 2


Başlarken


Bu modülü kullanmak için şunlara ihtiyacınız olacak:


*Python kurulu.


* Bir metin editörü


Matematik Araçları


"math-utils" modülü, toplama ve toplama gibi temel matematik işlevleri sağlar.
çıkarma.

Gerektiğinde daha fazla .rst dosyası ekleyebilirsiniz. Örneğin, aşağıdaki katkı yönergelerini içeren bir katkı kılavuzu oluşturabilirsiniz.

Katkı Rehberi
Projemize katkılarınızı bekliyoruz! İşte bazı yönergeler
katkı:


- Projeyi GitHub'da çatallayın.
- Değişikliklerinizi yeni bir şubede yapın.
- Değişikliklerinizin doğru çalıştığından emin olmak için testler yazın.
- Değişikliklerinizle birlikte bir çekme isteği gönderin.
- İstenen değişiklikleri yapın.
Katkıda bulunduğunuz için teşekkür ederiz!

Daha sonra toctree direktifine yeni bir bölüm ekleyerek bu dosyayı index.rst'den bağlayabilirsiniz:

.. toctree::
 :maksimum derinlik: 2
 :caption: İçindekiler Tablosu

 katkı

Bu, tıklandığında kullanıcıyı katkı sayfasına götüren içindekiler tablosunda katkıda bulunmak adlı yeni bir öğe oluşturur.

Belgeleri yazdıktan sonra, sonraki adım onu ​​oluşturmaktır. Burada dokümantasyonu oluşturmak, RST dosyalarından HTML, kılavuz veya PDF sayfaları oluşturmak anlamına gelir.

Dokümantasyonun Oluşturulması

Belgeleri Sphinx kullanarak oluşturmak için, makefile dosyasının bulunduğu klasörünüzün kök dizininde make html komutunu çalıştırmanız gerekecektir.

html yapmak

Oluşturma klasöründe HTML dosyalarını görmelisiniz. Derleme sırasında hatalar olursa, Sphinx terminalde size haber verecektir.

Belgeleri görüntülemek için tarayıcınızda index.html dosyasını açın:

İçindekiler tablosundan katkıda bulunma kılavuzuna gidebilmeniz gerekir.

Belgeleri Özelleştirme

Şu anda, belgelerde bazı temel stiller var. Özelleştirmek isterseniz, belki marka renklerinizi ekleyerek, hatta bir karanlık mod ekleyerek, diğerlerini yükleyebilir ve kullanabilirsiniz. yerleşik temalar veya kendi özel temanızı oluşturun.

Göstermek için temayı doğa olarak değiştirmeyi deneyin:

  1. Sphinx proje dizininizde Sphinx konfigürasyon dosyasını conf.py açın.
  2. html_theme seçeneğini tanımlayan satırı bulun ve onu doğa olarak değiştirin
  3. Yapılandırma dosyasını kaydedin ve değişikliklerinizi görmek için belgeleri yeniden oluşturun.

Belgelerin ana sayfası böyle görünmelidir.

Yerleşik temaları kullanmak istemiyorsanız, her zaman bir üçüncü taraf Sfenks teması yerine.

Belge Dizilerini Kullanarak Kodunuzu Belgeleme

Sphinx, Python belgelerinizi RST dosyalarına yazdığınız metinden oluşturur. Bu, bazı durumlarda yeterli olsa da, kodunuzdaki belge dizilerini modül düzeyinde kullanmak isteyebilirsiniz.

Belge dizileri doğrudan projenizin kaynak dosyalarının içinde yaşar. Kodun ne yaptığını açıklamanıza, örnekler vermenize ve hatta bu örnekler için testler oluşturmanıza olanak tanırlar. Belge dizeleri yazdıktan sonra, Sphinx'i kullanarak bunlardan belgeler oluşturabilirsiniz.