क्या Python दस्तावेज़ीकरण के लिए reStructuredText के लिए कोई वास्तविक विकल्प हैं?

Question

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

समस्या यह पुन: संरचित पाठ वाक्यविन्यास है जिसका उपयोग यह करता है - मुझे लगता है कि यह प्रस्तुत होने से पहले पूरी तरह से पढ़ा जा सकता है। उदाहरण के लिए:

 
:param path: The path of the file to wrap 
:type path: str 
:param field_storage: The :class:`FileStorage` instance to wrap 
:type field_storage: FileStorage 
:param temporary: Whether or not to delete the file when the File instance 
    is destructed 
:type temporary: bool 

आप को वास्तव में धीमा और कहा कि वाक्यात्मक गड़बड़ी से बाहर किसी भी समझ बनाने के लिए एक मिनट का समय दिया है।

 
Args: 
    path (str): The path of the file to wrap 
    field_storage (FileStorage): The FileStorage instance to wrap 
    temporary (bool): Whether or not to delete the file when the File 
     instance is destructed 

रास्ता अच्छे: मैं भी बहुत कुछ गूगल रास्ता (Google Python Style Guide) है, जो ऊपर के समकक्ष इस तरह दिखता है पसंद है! लेकिन निश्चित रूप से, स्फिंक्स में से कोई भी नहीं होगा और एक लंबी लाइन में "Args:" के बाद सभी पाठ प्रस्तुत करेगा।

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

Answer 1

मुझे नहीं लगता कि इस समय पाइथन परियोजनाओं को दस्तावेज करने के लिए sphinx से कुछ बेहतर है।

एक स्पष्ट डॉकस्ट्रिंग करने के लिए मेरी पसंदीदा पसंद sphinx का उपयोग numpydoc के साथ कर रही है।

def foo(path, field_storage, temporary): 
    """This is function foo 

    Parameters 
    ---------- 
    path : str 
     The path of the file to wrap 
    field_storage : :class:`FileStorage` 
     The :class:`FileStorage` instance to wrap 
    temporary : bool 
     Whether or not to delete the file when the File instance 
     is destructed 

    Returns 
    ------- 
    describe : type 
     Explanation 
    ... 

    Examples 
    -------- 
    These are written in doctest format, and should illustrate how to 
    use the function. 

    >>> a=[1,2,3] 
    >>> print [x + 3 for x in a] 
    [4, 5, 6] 
    ... 
    """ 

    pass 

(एक पूर्ण उदाहरण Here है), HTML आउटपुट की तरह this

मुझे लगता है कि पहला-फ़ाइल की संरचना स्पष्ट और अधिक पठनीय है दिखेगा: अपने उदाहरण के आधार पर इस प्रकार दिखाई देगा। guide कुछ और जानकारी और सम्मेलन देता है। numpydoc एक्सटेंशन autodoc के साथ भी काम करता है।

Answer 2

पायथन फ़ंक्शन/कक्षा/चरणीय ऑब्जेक्ट से जुड़े __doc__ विशेषता के रूप में उपलब्ध डॉकस्ट्रिंग की सामग्री बनाता है।

तो, आप आसानी से एक पाइथन प्रोग्राम लिख सकते हैं जो दस्तावेज को आपके इच्छित प्रारूप में जो भी प्रारूप पसंद करता है उसे परिवर्तित करता है। आप जावाडोक स्टाइल, या एक्सएमएल, या जो कुछ भी इस्तेमाल कर सकते हैं।

संयोग से, चूंकि स्फिंक्स पायथन में लिखा गया है, इसलिए इसे गैर-आरएसटी इनपुट लेना सिर्फ थोड़ी मात्रा में पायथन कोड लिखना है।

Answer 3

दरअसल, reStructuredText साथ ही PEP8 से स्टाइल गाइड भी पाइथन की मानक लाइब्रेरी को कोडिंग के लिए लागू होता है, हालांकि बहुत से तृतीय पक्ष प्रोग्रामर भी इसके अनुरूप होते हैं।

मैं आपसे सहमत हूं कि तर्क के लिए Google की शैली इन-कोड परिप्रेक्ष्य से काफी बेहतर है। लेकिन आप generate such docstring with sphinx के साथ-साथ with the new lines and indentation preserved पर भी सक्षम होना चाहिए। यह with a more sphinxy formatting के रूप में अच्छा उत्पादन नहीं करता है।

वैसे भी, आप नहीं करने के लिए है उपयोग स्फिंक्स करते हैं, और वैसे, स्फिंक्स की autodoc मॉड्यूल निश्चित रूप से इसे का एक छोटा सा हिस्सा है। आप वस्तुतः किसी भी दस्तावेज जनरेटर का उपयोग कर सकते हैं जो Epydoc (epytext के साथ-साथ reStructuredText, Javadoc or Plaintext) या pydoctor या Doxygen जैसे अधिक सार्वभौमिक की तरह डॉकस्ट्रिंग की सामग्री को पुनर्प्राप्त करने में सक्षम है।

लेकिन निश्चित रूप से, स्फिंक्स काफी पायथनिक है, जो पाइथन के साथ उपयोग करने के लिए बहुत सुविधाजनक है, और पाइथन के पारिस्थितिक तंत्र के साथ अपना कोड सुसंगत बनाते हैं। मुझे लगता है कि आप not the only one हैं जो सोचते हैं कि यह "कमी" है। हो सकता है कि वे भविष्य में इन शिकायतों को ध्यान में रख सकें, या हो सकता है कि आप अपने आप से autodoc मॉड्यूल को मॉडिफ़िंग करने पर विचार करें, यह बहुत कठिन नहीं होना चाहिए, यह पायथन में है, यह एक अच्छा अभ्यास होगा।

Answer 4

आप किसी भी प्रारूप में डॉकस्ट्रिंग लिख सकते हैं। हालांकि, हर दूसरे पायथन प्रोग्रामर के लिए, मार्कअप और टूल्स का उपयोग करना सबसे अच्छा है जो वे पहले से जानते हैं। यदि आप रीस्ट और स्फिंक्स से चिपके रहते हैं तो उनका जीवन आसान होता है।

Answer 5

मैं epydoc का उपयोग करता हूं और स्फिंक्स नहीं, इसलिए यह उत्तर लागू नहीं हो सकता है।

विधियों और कार्यों को दस्तावेज करने के लिए आप पुन: संरचित टेक्स्ट सिंटैक्स का वर्णन केवल एकमात्र संभव नहीं है। अब तक, मैं एक consolidated definition list, जो बहुत ही गूगल रास्ते के समान है का उपयोग कर मानकों का वर्णन पसंद करते हैं:

:Parameters: 
    path : str 
    The path of the file to wrap 
    field_storage: FileStorage 
    The FileStorage instance to wrap 
    temporary: bool 
    Whether or not to delete the file when the File instance is destructed 

मैं sphix यह समर्थन करता है तो बाहर की कोशिश करेंगे। यदि ऐसा नहीं होता है तो आप इसके लिए epydoc का उपयोग करने पर भी विचार कर सकते हैं (हालांकि यह अभी सक्रिय रूप से बनाए रखा नहीं गया है)।

Answer 6

आपको बस एक नई लाइन शुरू करने और प्रत्येक चर नाम के बाद एक टैप जोड़ने की आवश्यकता है। तो फिर यह consucutive बोल्ड चर नाम के साथ कई लाइनों में प्रदान की गई है:

Args: 
    path (str): 
     The path of the file to wrap 
    field_storage (FileStorage): 
     The FileStorage instance to wrap 
    temporary (bool): 
     Whether or not to delete the file when the File 
     instance is destructed 

Answer 7

मैं एक Sphinx extension कि दोनों गूगल शैली और NumPy शैली docstrings पार्स करता है, और उन्हें मानक reStructuredText में धर्मान्तरित बनाया है। नेपोलियन here पर

# conf.py 

# Add autodoc and napoleon to the extensions list 
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] 

अधिक प्रलेखन:

इसका इस्तेमाल के लिए, बस इसे स्थापित:

$ pip install sphinxcontrib-napoleon 

और conf.py में सक्षम।