जावाडोक से पायथन तक माइग्रेट करना प्रलेखन

Question

तो मुझे कुछ हद तक जावाडोक शैली प्रलेखन में उपयोग किया गया है। पाइथन कोड के विभिन्न उदाहरणों के माध्यम से देखकर, मुझे लगता है कि, पहले ब्लश पर, प्रलेखन बहुत सारी जानकारी खोने के लिए प्रतीत होता है।

अच्छा: आप शायद ही कभी दस्तावेज के स्वयं स्पष्ट बिट्स देखते हैं। डॉकस्ट्रिंग आमतौर पर एक अनुच्छेद या अंग्रेजी मार्कअप का कम होता है जो अलग-अलग लाइनों पर खड़े होने के बजाय एकीकृत करता है।

खराब: पायथन के बतख-टाइपिंग के संयोजन के साथ, मुझे लगता है कि कई फ़ंक्शन उन पैरामीटरों के बारे में अस्पष्ट हैं जिन्हें वे उम्मीद करते हैं। कोई प्रकार संकेत नहीं है (बतख-संकेत?) और अक्सर यह अच्छा लगता है कि पैरामीटर सूची-जैसे, स्ट्रिंग-जैसी, स्ट्रीम-जैसी होना चाहिए।

बेशक, जैवडोक को पायथन के महान आत्मनिरीक्षण क्षमताओं के बिना निम्न स्तर की भाषा के लिए डिज़ाइन किया गया था, जो कम वर्बोज़ दस्तावेज़ दर्शन के लिए जिम्मेदार हो सकता है।

पायथन दस्तावेज़ मानकों और सर्वोत्तम प्रथाओं पर कोई सलाह?

Answer 1

reStructuredText प्रारूप कि docstrings में एम्बेड किया जा सकता है अजगर प्रलेखन के लिए की जरूरत के जवाब में डिजाइन किया गया था, तो सबसे अच्छी बात करने के लिए बाकी जानने के लिए और उस प्रारूप के साथ अपने docstrings स्वरूप है। तुम्हें पता है, मिल सकती है के रूप में मैंने किया था, कि तुम तो प्रारूप सिर्फ बाकी हिस्सों में के बारे में किसी भी प्रलेखन पर जाने, लेकिन यह एक पक्ष बिंदु :-)

विशेष रूप से अपने अजगर कोड का दस्तावेजीकरण के लिए है, Sphinx प्रणाली का एक सेट है रीस्ट प्रारूप में एक्सटेंशन, और दस्तावेजों को प्रस्तुत करने के लिए एक बिल्ड सिस्टम। चूंकि इसे मानक लाइब्रेरी समेत पाइथन को दस्तावेज करने के लिए डिज़ाइन किया गया था, स्फिंक्स स्रोत कोड के बहुत अच्छी तरह से संरचित प्रलेखन के लिए अनुमति देता है, जिसमें आप पूछ रहे हैं फ़ंक्शन हस्ताक्षर के विनिर्देशों सहित। यह एक व्यापक प्रलेखन सूट का निर्माण करने की अनुमति देता है, दोनों ऑटो-निकाले गए और हाथ से लिखे गए, सभी समान स्वरूपण प्रणाली का उपयोग करते हैं।

यदि आप केवल चाहते प्रलेखन अपने स्रोत कोड से उत्पन्न है, तो Epydoc अपने स्रोत कोड से API दस्तावेज़ निकालने जाएगा; यह भी पाठ के लिए पुन: स्वरूपण पढ़ता है।