Doxygen'in C veya PHP kodunun belgelerini oluşturmasını seviyorum. Yaklaşan bir Python projem var ve sanırım Python'un /* .. */yorumları olmadığını ve ayrıca kendi kendini belgeleme olanağına sahip olduğunu hatırlıyorum, bu da pitonik bir yol gibi görünüyor.
Doxygen'e aşina olduğuma göre, Python belgelerimi oluşturmak için onu nasıl kullanabilirim? Özellikle bilmem gereken bir şey var mı?
Yanıtlar:
Bu, doxygen web sitesinde belgelenmiştir , ancak burada özetlemek gerekirse:
Python kodunuzu belgelemek için doxygen kullanabilirsiniz. Python dokümantasyon dizesi sözdizimini kullanabilirsiniz:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
Bu durumda yorumlar doxygen tarafından alınacaktır, ancak özel doxygen komutlarından herhangi birini kullanamazsınız .
Veya (doxygen altındaki C-stili dillere benzer şekilde #) üyeden önceki ilk satırdaki yorum işaretçisini ( ) ikiye katlayabilirsiniz :
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
Bu durumda, özel doxygen komutlarını kullanabilirsiniz. Orada özel bir Python çıkış modu, ama görünüşe göre ayarlayarak sonuçları geliştirebilirsiniz OPTMIZE_OUTPUT_JAVAiçin YES.
Dürüst olmak gerekirse, fark beni biraz şaşırttı - görünüşe göre doxygen ## blok veya "" "bloklardaki yorumları algılayabildiğinde, işin çoğu yapılacak ve özel komutları kullanabileceksiniz. Belki de "" "kullananların daha fazla Pythonic dokümantasyon uygulamasına bağlı kalmasını ve bu da özel doxygen komutlarına müdahale etmesini bekliyorlar?
Doxypy giriş filtresi standart bir Python docstring'ini formatında hemen hemen tüm Doxygen en biçimlendirme etiketlerinin kullanmasına olanak sağlar. Büyük bir karma C ++ ve Python oyun uygulama çerçevesini belgelemek için kullanıyorum ve iyi çalışıyor.
Sonunda, sadece iki seçeneğiniz var:
İçeriğinizi Doxygen kullanarak oluşturursunuz veya içeriğinizi Sphinx * kullanarak oluşturursunuz.
Doxygen : Çoğu Python projesi için tercih edilen bir araç değildir. Ancak, C veya C ++ ile yazılmış diğer ilgili projelerle uğraşmanız gerekiyorsa, bu mantıklı olabilir. Bunun için doxypy kullanarak Doxygen ve Python arasındaki entegrasyonu geliştirebilirsiniz .
Sphinx : Bir Python projesini belgelemek için kullanılan fiili araç. Burada üç seçeneğiniz var: manuel, yarı otomatik (saplama oluşturma) ve tam otomatik (Doxygen benzeri).
autosummary_generateYapılandırma sisteminizi sphinx-autogen'i çağıracak şekilde kurabilir veya Sphinx'inizi yapılandırma ile ayarlayabilirsiniz . Otomatik özetler içeren bir sayfa ayarlamanız ve ardından sayfaları manuel olarak düzenlemeniz gerekecektir. Seçenekleriniz var, ancak bu yaklaşımla ilgili deneyimim, çok fazla yapılandırma gerektirdiğidir ve sonunda yeni şablonlar oluşturduktan sonra bile, hatalar buldum ve tam olarak neyin genel API olarak açıklandığını ve neyin olmadığını belirlemenin imkansızlığını buldum. Bence bu araç, manuel düzenleme gerektiren saplama üretimi için iyidir ve başka bir şey değildir. El kitabına son vermek için bir kısayol gibidir.Dikkat edilmesi gereken başka seçenekler de var:
__all__ .
Sphinx, anladığım kadarıyla esas olarak kaynak koddan bağımsız olarak yazılmış belgeleri biçimlendirmek için bir araçtır.
Python docstrings'den API belgeleri oluşturmak için önde gelen araçlar pdoc ve pydoctor'dur . İşte pydoctor'un Twisted ve Bazaar için ürettiği API belgeleri .
Elbette, bir şeyler üzerinde çalışırken sadece doküman dizilerine bakmak isterseniz, " pydoc " komut satırı aracı ve help()etkileşimli yorumlayıcıda bulunan işlev vardır.
Diğer çok iyi bir belgeleme aracı da sfenkstir . Yaklaşan python 2.6 dokümantasyonu için kullanılacak ve django ve diğer birçok python projesi tarafından kullanılacak .
Sfenks web sitesinden: