Sphinx ile Belgelendirme ve GitLab Entegrasyonu

Artistanbul olarak kod kalitesine önem veriyoruz ve her projenin belgelemesinin doğru yapılmasını istiyoruz. Bunlar yapılırken birden fazla proje üzerinde çalışıldığı için her geliştiricinin tekrarladığı işler olduğunu fark ettik. Bu işlerden en önemlisi, dizin ve dosya yapısı ile beraber belgelemenin nasıl yapılacağı idi. Bu problemi çözmek için GitLab’ın sunduğu şablon repo özelliğini kullandık. Özetle, GitLab üzerinde yeni proje açılırken önceden açılmış bir repoyu ilk commit olarak kullanabiliyorsunuz. Bu da size herkesin kullanabileceği bir şablon oluşturarak, tekrarlayan işlerin önüne geçmenizi sağlıyor. Bu blog girdisinde Sphinx ile Python projeleri için nasıl belgeleme yapılacağını, GitLab entegrasyonunu, kod örneklerini, dizin yapısını ve hazır ayar dosyalarını bulacaksınız.

 

Python Docstring ve Sphinx

Python fonksiyon ve sınıflarda belgeleme yapmanıza olanak sağlıyor. Muhtemelen karşınıza çıkmıştır, üç tırnak (“””) ile başlar ve aynı şekilde biter. Fonksiyonların açıklamaları, hangi parametreleri aldığı, sınıfların metodları ve detayları gibi bilgiler buraya yazılabiliyor. Örneğin:

def foo(self, parametre):
    """
    Dictionary içerisinde gelen verilere göre faydalı işler yapar

    :param parametre: parametre açıklaması
    :return: başarılı olduğunda True, hata veya başka bir durumda exception
    :raise FooLimitException: API tarafında limite takıldığında
    :raise FooDeclinedException: İşlem yapılamadığında. İçerisinde hata kodu ve neden geri çevrildiği mevcut
    """

Burada gördüğünüz rST formatında bir docstring açıklaması. rST gibi bir format kullanmak hem belgeleme araçlarını kullanabilmenizi sağlıyor, hem de IDE desteği olduğu için her geliştirici hangi formatta yazması gerektiğini önceden bilmiş oluyor. Sphinx bu noktada devreye giriyor. Python ile yazılmış bir belge üretme aracı olan Sphinx yapılandırıldıktan sonra bütün projenizdeki metodları readthedocs teması ile kolay okunabilir bir şekilde sunuyor. İlk başta kurulumu zor görünebileceği için kolay kullanılır şekilde Sphinx kullanımına geçebiliriz.

 

Sphinx kurulumu

Sphinx bir Python projesi olduğu için pip ile kuracağız ancak beraberinde en çok kullandığımız markdown, readthedocs, todo gibi araçlar olacağı için hepsini beraber kuracağız.

Burada virtualenv altında çalıştığınızı ve bunun hakkında bilgi sahibi olduğunuzu tahmin ederek devam ediyorum. Eğer virtualenv kullanmıyorsanız, lütfen bu paketleri sisteminize kurmayın, virtualenv kullanmaya başladıktan sonra buradan devam edin.

pip install sphinx sphinx-rtd-theme myst-parser

Sonrasında Sphinx hızlı başlangıç uygulamasını çalıştırarak sorulara yanıt verin ve belgeleme dizinlerini oluşturun.

sphinx-quickstart

Bu komut sonucunda dizin yapınız aşağıdakine benzer olmalı:

.
├── Makefile
├── README.md
├── build
├── docs
│   ├── _static
│   ├── _templates
│   ├── conf.py
│   └── index.rst
├── mylibrary
│   └── client.py
└── requirements.txt

Burada boş repoya ek olarak mylibrary kütüphanesi ve README mevcut. bunlar dışında Sphinx kullanmaya hazırız ancak conf.py içerisinde hangi uzantıları kullanacağımızı ve temamızı belirlememiz gerekiyor. conf.py dosyasını açın ve düzenleyin. Sonrasında aşağıdaki satırları ekleyeceğiz.

# ...
# ...

extensions = [
    "sphinx_rtd_theme",
    "myst_parser",
    "sphinx.ext.autodoc",
    "sphinx.ext.todo",
]

todo_include_todos = True

# ...
# ...

html_theme = 'sphinx_rtd_theme'

Kullanmaya hazırız ancak hâlâ Sphinx’e modüllerimizi otomatik olarak alıp docstring çıkarmasını söylemedik. index.rstdosyasına hangi modüle bakmasını gerektiğini söyleyeceğiz. Bunu başka bir dosya da yapabilirdik ancak örneğin kısalığı açısından index kullanıyoruz.

.. automodule:: mylibrary.client
   :members:
   :inherited-members:
   :show-inheritance:

Dikkat ettiyseniz automodule tanımlamasında mylibrary.client kullandım. Bu modül import edilebilir halde olmalı. Dolayısıyla proje dizinimiz içerisinde çalışırken PYTHONPATH bu dizine de sahip olmalı. Belgelerimizi oluşturmadan önce Makefile dosyasında bunu düzeltelim.

# ...
SOURCEDIR     = docs
BUILDDIR      = build

# Sphinx modül aratırken şu andaki dizine bakmıyor. Bu yüzden bu dizini
# path'e eklemek zorundayız.
export PYTHONPATH := .

#...

Burada source ve build dizinlerini başka şekilde de ayarlayabilirsiniz ancak docs/ ve build/ isimlendirmesi yeterli. Bu dizinleri .gitignore dosyanıza eklemeyi unutmayın.

 

Sphinx kullanımı

Bütün bu ayarları yaptıktan sonra kullanım çok basit. Proje dizinine girip,

make html

komutunu yazmanız yeterli. Bu build/html/ dizini altında bütün sayfayı oluşturacak. Konsol üzerinden hemen açmak için open build/html/index.html komutunu kullanabilirsiniz.

 

GitLab sayfaları

Kodlarımızı yine şirket içerisinde tutuyoruz ve bunun için GitLab kullanıyoruz. GitLab proje bazlı statik web sayfalarını sunabiliyor. Bu sayfaların otomatik güncellenmesi ve yayına alınması da yine CI/CD üzerinden rahatlıkla gerçekleşebiliyor.

Projelerin statik sayfaları hazır olduğundan tek yapmamız gereken .gitlab-ci.yml içerisinde html çıktı dizinini verip oluşturmasını beklemek. Bunun için aşağıdaki YAML dosyasını örnek alabilirsiniz. Python projesi olduğu için CI/CD çalışırken de virtualenv kullanıldığını hatırlatalım.

mage: python:latest

cache:
  paths:
    - .cache/pip
    - venv/

pages:
  script:
    - python -v # CI işinde sorun olursa debug için kullanıyoruz
    - pip install -r requirements.txt
    - make html
    - mv build/html/ public/
  artifacts:
    paths:
      - public
  only:
    - main

Bu tanımlamalarla birlikte artık bütün projemiz hazır. Commit yapıldığında GitLab sayfası otomatik olarak oluşturulup, GitLab Pages ile sunmaya başlayacak. Belge adresi GitLab kurulumunuza ve repo isminize göre değişiklik gösterecektir.

 

Sonuç

Kod yazarken rST formatında metod belgelendirmesi yaparak hem kod kalitesini artırmış, hem de güzel bir web arayüzü ile bütün metodların açıklamalarını görebilir hale geldik. Bu, birden fazla projenin aynı anda yürüdüğü bir şirket için gerçekten önem teşkil ediyor zira kod reposu içerisinde standardın olması işlerin daha hızlı şekilde yürümesine olanak sağlıyor.

Söz uçar, yazı kalır boşuna söylenmiş bir söz değil. Eğer takım içerisinde belgeleme pratiklerinin önünü açmaz ve kolay hale getirmezsek kod yazıp hızlıca ilerlemek isteyen geliştiriciler belgelemeye zaman bulamıyor ve bu şekilde kalıyor. Hazır ve çalışan bir altyapıyı kullanmak ve düzeltmek, baştan başlamaya göre çok daha kolay. Bu yüzden bu blog yazısında yazılanlar kendi içimizde bir repo haline getirildi ve yeni proje oluşturulurken şablon olarak kullanılmak üzere ayarlandı.

Artık boş projeler API belgelemesi, README dosyası, kod örnekleri ve belgeleme araçları ile geliyor, kod kalitemizi arttırmış oluyoruz.