मुझे C या PHP कोड के प्रलेखन बनाने के लिए Doxygen पसंद है। मेरे पास एक आगामी पायथन परियोजना है और मुझे लगता है कि मुझे याद है कि पायथन में /* .. */टिप्पणियां नहीं हैं , और इसकी अपनी स्वयं की प्रलेखन सुविधा भी है जो दस्तावेज़ के लिए पायथोनिक तरीका लगता है।
चूँकि मैं Doxygen से परिचित हूँ, मैं इसका उपयोग अपने पायथन डॉक्यूमेंटेशन को बनाने के लिए कैसे कर सकता हूँ? क्या विशेष रूप से ऐसा कुछ है जिससे मुझे अवगत होने की आवश्यकता है?
जवाबों:
यह डॉक्यूमेंट्री वेबसाइट पर प्रलेखित है , लेकिन यहां संक्षेप में प्रस्तुत करने के लिए:
आप अपने पायथन कोड को दस्तावेज़ करने के लिए doxygen का उपयोग कर सकते हैं। आप या तो पायथन प्रलेखन स्ट्रिंग सिंटैक्स का उपयोग कर सकते हैं:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
जिस स्थिति में टिप्पणियाँ doxygen द्वारा निकाली जाएंगी, लेकिन आप किसी विशेष doxygen कमांड का उपयोग नहीं कर पाएंगे ।
या आप (doxygen के तहत सी-शैली भाषाओं के समान #) सदस्य से पहले पहली पंक्ति में टिप्पणी मार्कर ( ) को दोगुना कर सकते हैं :
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
उस स्थिति में, आप विशेष doxygen कमांड का उपयोग कर सकते हैं। कोई खास अजगर उत्पादन मोड है, लेकिन आप जाहिरा तौर पर सेट करके परिणामों में सुधार कर सकते हैं OPTMIZE_OUTPUT_JAVAकरने के लिए YES।
ईमानदारी से, मैं अंतर पर थोड़ा आश्चर्यचकित हूं - ऐसा लगता है जैसे एक बार doxygen ## ब्लॉक या "" ब्लॉक में टिप्पणियों का पता लगा सकता है, अधिकांश काम किया जाएगा और आप विशेष कमांड का उपयोग करने में सक्षम होंगे; या तो मामला। हो सकता है कि वे लोगों को "" "" का उपयोग करने की अपेक्षा करते हैं जो अधिक पायथनिक अभ्यास प्रथाओं का पालन करते हैं और जो विशेष डॉक्सीजन कमांड के साथ हस्तक्षेप करेंगे?
Doxypy इनपुट फ़िल्टर आप काफी सभी Doxygen के स्वरूपण टैग की एक मानक अजगर docstring प्रारूप में उपयोग करने के लिए अनुमति देता है। मैं इसे एक बड़े मिश्रित C ++ और पायथन गेम एप्लिकेशन फ्रेमवर्क को दस्तावेज करने के लिए उपयोग करता हूं, और यह अच्छी तरह से काम कर रहा है।
अंत में, आपके पास केवल दो विकल्प हैं:
आप अपनी सामग्री को Doxygen का उपयोग करके उत्पन्न करते हैं, या आप Sphinx * का उपयोग करके अपनी सामग्री उत्पन्न करते हैं।
Doxygen : यह अधिकांश पायथन परियोजनाओं के लिए पसंद का उपकरण नहीं है। लेकिन अगर आपको C या C ++ में लिखी गई अन्य संबंधित परियोजनाओं से निपटना है तो यह समझ में आ सकता है। इसके लिए आप डॉक्सीपाइप का उपयोग करके Doxygen और Python के बीच एकीकरण में सुधार कर सकते हैं ।
स्फिंक्स : पायथन परियोजना के दस्तावेजीकरण के लिए डिफेक्टो टूल। आपके पास यहां तीन विकल्प हैं: मैनुअल, सेमी-ऑटोमेटिक (स्टब जेनरेशन) और पूरी तरह से ऑटोमैटिक (डॉक्सिजन जैसे)।
autosummary_generateकॉन्फ़िगरेशन के साथ सेटअप कर सकते हैं । आपको आटोसमरियों के साथ एक पृष्ठ सेटअप करना होगा, और फिर मैन्युअल रूप से पृष्ठों को संपादित करना होगा। आपके पास विकल्प हैं, लेकिन इस दृष्टिकोण के साथ मेरा अनुभव यह है कि इसके लिए बहुत अधिक कॉन्फ़िगरेशन की आवश्यकता होती है, और अंत में नए टेम्प्लेट बनाने के बाद भी, मुझे बग और सार्वजनिक एपीआई के रूप में क्या उजागर किया गया था, यह निर्धारित करने के लिए कीड़े और असंभवता मिली। मेरी राय है कि यह उपकरण स्टब जनरेशन के लिए अच्छा है जिसे मैनुअल एडिटिंग की आवश्यकता होगी, और इससे ज्यादा कुछ नहीं। मैन्युअल में समाप्त होने के लिए एक शॉर्टकट की तरह है।नोट करने के लिए अन्य विकल्प हैं:
__all__।
स्फिंक्स मुख्य रूप से स्रोत कोड से स्वतंत्र रूप से लिखे गए डॉक्स को प्रारूपित करने का एक उपकरण है, जैसा कि मैं इसे समझता हूं।
अजगर डॉक्सिंग से एपीआई डॉक्स उत्पन्न करने के लिए, प्रमुख उपकरण पीडीओक और पीडोक्टर हैं । यहाँ ट्विस्टेड और बाज़ार के लिए pydoctor का जनरेट किया गया एपीआई डॉक्स है ।
बेशक, अगर आप सामान पर काम करते समय डॉकस्ट्रिंग्स पर एक नज़र रखना चाहते हैं, तो " pydoc " कमांड लाइन टूल और साथ ही साथ help()इंटरएक्टिव इंटरप्रेटर में उपलब्ध फ़ंक्शन भी है।
एक अन्य बहुत अच्छा प्रलेखन उपकरण स्फिंक्स है । यह आगामी अजगर 2.6 प्रलेखन के लिए इस्तेमाल किया जाएगा और django और कई अन्य अजगर परियोजनाओं द्वारा उपयोग किया जाता है ।
स्फिंक्स वेबसाइट से: