डॉक्सिजन

Question

के साथ पायथन कोड को कैसे दस्तावेज़ित करें मुझे सी या PHP कोड के दस्तावेज़ बनाने के लिए डॉक्सिजन पसंद है। मेरे पास एक आगामी पायथन परियोजना है और मुझे लगता है कि मुझे याद है कि पायथन में /* .. */ टिप्पणियां नहीं हैं, और इसकी स्वयं की स्वयं-प्रलेखन सुविधा भी है जो दस्तावेज़ के लिए पाइथोनिक तरीका प्रतीत होती है।

चूंकि मैं डॉक्सिजन से परिचित हूं, मैं अपने पायथन दस्तावेज़ों का उत्पादन करने के लिए इसका उपयोग कैसे कर सकता हूं? क्या विशेष रूप से कुछ भी है जिसके बारे में मुझे अवगत होना चाहिए?

Answer 1

यह documented on the doxygen website है, लेकिन यहाँ संक्षेप में प्रस्तुत करने के लिए:

आप अपने अजगर कोड दस्तावेज़ के लिए Doxygen का उपयोग कर सकते हैं। आप अजगर प्रलेखन स्ट्रिंग सिंटैक्स का उपयोग या तो कर सकते हैं:

"""@package docstring 
Documentation for this module. 

More details. 
""" 

def func(): 
    """Documentation for a function. 

    More details. 
    """ 
    pass 

जो मामले में टिप्पणी Doxygen से निकाला जाएगा, लेकिन आप special doxygen commands के किसी भी उपयोग करने में सक्षम नहीं होगा।

या आप (Doxygen के तहत सी-शैली भाषाओं के समान) तक दोगुना सदस्य से पहले पहली पंक्ति पर टिप्पणी मार्कर (#) कर सकते हैं:

## @package pyexample 
# Documentation for this module. 
# 
# More details. 

## Documentation for a function. 
# 
# More details. 
def func(): 
    pass 

उस मामले में, आप उपयोग कर सकते हैं विशेष डॉक्सिजन कमांड। कोई विशेष पायथन आउटपुट मोड नहीं है, लेकिन आप OPTMIZE_OUTPUT_JAVA से YES पर सेट करके परिणामों को स्पष्ट रूप से सुधार सकते हैं।

ईमानदारी से, मैं अंतर पर थोड़ा आश्चर्यचकित हूं - ऐसा लगता है कि एक बार डॉक्सिजन ## ब्लॉक या ब्लॉक में टिप्पणियों का पता लगा सकता है, अधिकांश काम किया जाएगा और आप इसका उपयोग करने में सक्षम होंगे किसी भी मामले में विशेष आदेश। शायद वे लोगों को अधिक पाइथनिक प्रलेखन प्रथाओं का पालन करने के लिए "" प्रयोग करने की उम्मीद करते हैं और इससे विशेष डॉक्सिजन कमांड में हस्तक्षेप होगा?

Answer 2

एक अन्य बहुत अच्छा दस्तावेज उपकरण sphinx है। इसका उपयोग आगामी पायथन 2.6 documentation के लिए किया जाएगा और django और कई अन्य पायथन परियोजनाओं द्वारा उपयोग किया जाता है।

स्फिंक्स वेबसाइट से:

• आउटपुट प्रारूपों: HTML और LaTeX, प्रिंट करने योग्य PDF संस्करण
• व्यापक पार संदर्भ के लिए (विंडोज HTML सहायता सहित): अर्थ मार्कअप और के लिए स्वचालित लिंक कार्य, कक्षाएं, शब्दावली शब्द और जानकारी के समान टुकड़े
• पदानुक्रमित संरचना: दस्तावेज़ पेड़ की आसान परिभाषा, सिबली के स्वचालित लिंक के साथ ngs, माता पिता और बच्चों
• स्वचालित सूचकांक: सामान्य सूचकांक के साथ ही एक मॉड्यूल सूचकांक
• कोड से निपटने: स्वचालित Pygments का उपयोग कर हाइलाइटिंग हाइलाइटर
• एक्सटेंशन: कोड के टुकड़े का स्वत: परीक्षण, के शामिल किए जाने पायथन मॉड्यूल से डॉकस्ट्रिंग, और

Answer 3

स्फिंक्स मुख्य रूप से स्रोत कोड से स्वतंत्र रूप से लिखे गए प्रारूपण प्रारूपों के लिए एक उपकरण है, जैसा कि मैं समझता हूं।

पायथन डॉकस्ट्रिंग से एपीआई दस्तावेज़ बनाने के लिए, अग्रणी उपकरण pdoc और pydoctor हैं। Twisted और Bazaar के लिए पाइडक्टर के जेनरेट किए गए एपीआई दस्तावेज़ यहां दिए गए हैं।

बेशक, यदि आप सामान पर काम करते समय डॉकस्ट्रिंग को देखना चाहते हैं, तो "pydoc" कमांड लाइन टूल और help() इंटरैक्टिव दुभाषिया में उपलब्ध फ़ंक्शन उपलब्ध है।

Answer 4

doxypy इनपुट फ़िल्टर आपको मानक पायथन डॉकस्ट्रिंग प्रारूप में डोक्सिजन के स्वरूपण टैग के बहुत सारे उपयोग करने की अनुमति देता है। मैं इसे एक बड़े मिश्रित सी ++ और पायथन गेम एप्लिकेशन ढांचे को दस्तावेज करने के लिए उपयोग करता हूं, और यह अच्छी तरह से काम कर रहा है। *

आप Doxygen का उपयोग अपनी सामग्री उत्पन्न, या आप स्फिंक्स का उपयोग अपनी सामग्री उत्पन्न:

Answer 5

अंत में, आप केवल दो विकल्प हैं।

1. Doxygen: यह सबसे अजगर परियोजनाओं के लिए पसंद की उपकरण नहीं है। लेकिन अगर आपको सी या सी ++ में लिखी गई अन्य संबंधित परियोजनाओं से निपटना है तो यह समझ में आ सकता है। इसके लिए आप doxypypy का उपयोग कर डॉक्सीजन और पायथन के बीच एकीकरण में सुधार कर सकते हैं।

2. स्फिंक्स: पायथन परियोजना को दस्तावेज करने के लिए डिफैक्टो टूल। आपके पास यहां तीन विकल्प हैं: मैन्युअल, सेमी-ऑटोमैटिक (स्टब पीढ़ी) और पूरी तरह से स्वचालित (डॉक्सिजन जैसे)।

   1. मैन्युअल एपीआई दस्तावेज के लिए आपके पास स्फिंक्स autodoc है। एम्बेड किए गए एपीआई जेनरेट किए गए तत्वों के साथ उपयोगकर्ता मार्गदर्शिका लिखना बहुत अच्छा है।
   2. सेमी-स्वचालित के लिए आपके पास स्फिंक्स autosummary है। आप या तो sphinx-autogen को कॉल करने के लिए अपनी बिल्ड सिस्टम सेट कर सकते हैं या autosummary_generate कॉन्फ़िगरेशन के साथ अपना स्फिंक्स सेट कर सकते हैं। आपको autosummaries के साथ एक पृष्ठ सेट अप करने की आवश्यकता होगी, और उसके बाद पृष्ठों को मैन्युअल रूप से संपादित करें। आपके पास विकल्प हैं, लेकिन इस दृष्टिकोण के साथ मेरा अनुभव यह है कि इसे बहुत अधिक विन्यास बनाने की आवश्यकता है, और अंत में नए टेम्पलेट्स बनाने के बाद भी, मुझे बग और असंभवता यह निर्धारित करने के लिए मिली कि वास्तव में सार्वजनिक एपीआई के रूप में क्या खुलासा हुआ था और क्या नहीं। मेरी राय यह है कि यह उपकरण स्टब पीढ़ी के लिए अच्छा है जिसके लिए मैन्युअल संपादन की आवश्यकता होगी, और कुछ भी नहीं। मैनुअल में खत्म करने के लिए एक शॉर्टकट की तरह है।
   3. पूरी तरह से स्वचालित। इस पर कई बार आलोचना की गई है और लंबे समय तक हमारे पास स्पिंक्स के साथ एकीकृत एक पूर्णतः पूर्ण पाइथन एपीआई जेनरेटर नहीं था जब तक AutoAPI आया, जो ब्लॉक में एक नया बच्चा है। पायथन में स्वचालित एपीआई पीढ़ी के लिए यह अब तक का सबसे अच्छा है (नोट: लापरवाह स्व-पदोन्नति)।

अन्य विकल्पों पर ध्यान देना रहे हैं:

• Breathe: यह एक बहुत ही अच्छा विचार के रूप में शुरू किया, और समझ है जब आप अन्य भाषाओं कि Doxygen का उपयोग में कई संबंधित परियोजना के साथ काम करता है। विचार Doxygen XML आउटपुट का उपयोग करना है और इसे अपने एपीआई उत्पन्न करने के लिए स्फिंक्स को फ़ीड करना है। तो, आप Doxygen की सभी भलाई रख सकते हैं और स्फिंक्स में प्रलेखन प्रणाली को एकीकृत कर सकते हैं। सिद्धांत में बहुत बढ़िया। अब, व्यावहारिक रूप से, मैंने पिछली बार परियोजना की जांच की थी, उत्पादन के लिए तैयार नहीं था।
• pydoctor *: बहुत खास। अपना खुद का उत्पादन उत्पन्न करता है। इसमें स्फिंक्स के साथ कुछ बुनियादी एकीकरण है, और कुछ अच्छी विशेषताएं हैं।