Read the Docs (RTD) genel olarak yazılım dökümantasyonu olarak kullanılsa da farklı dökümantasyon ihtiyaçları için de kullanılabilmektedir. Basitleştirilmiş yapısı ile versiyon kontrol sistemi üzerinde bulunan depodan otomatik olarak dosyaları çeker, sizin için derler ve sunar. Ben akademik dökümantasyon işlerimde kullanıyorum.
Burada karşılaştığım sorun, eklenti (extension) kullandığım zaman kendi yerel bilgisayarımda derlemeler sorunsuz olmasına karşın RTD üzerinde derleme hatası vermesiydi. Bu hatayı gidermek için RTD üzerinde Gelişmiş Ayarlar (Advanced Settings) kısmında Gereksinimler Dosyası (Requirements file) alanı bulunuyor. Buraya genellikle “requirements.txt” yazarak, bu dosyayı da ana dizine eklemek yeterli oluyor. Tabi “requirements.txt” dosyasının içeriğine sadece çalışmak istediğimiz eklentinin ismini yazmamız yeterli. Bu dosyayla ilgili daha detaylı bilgi edinmek için burayı ziyaret edebilirsiniz.
Örnek bir uygulamayı Github üzerinde bulunan RTD-Sphinx-Theme-Basic depomda bulabilirsiniz.
Kaynak:
[1] not building .html using readthedocs.org, https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/107, (13.09.2018)
[2] Pypa User Guide – Requirements File, https://pip.pypa.io/en/latest/user_guide/#requirements-files, (13.09.2018)