मैं एक numpy- जैसे दस्तावेज कैसे बना सकता हूँ?

Question

मैं स्पाइडर और वस्तु निरीक्षक के साथ एक बहुत है, जो मैं एक पल मदद समारोह के रूप में बहुत सुविधाजनक लगता है काम कर रहा हूँ। कुछ मॉड्यूल इस समारोह से बहुत अच्छी तरह से लाभ लगते हैं। उदाहरण के लिए एक बहुत बुनियादी numpy समारोह (numpy.absolute) वस्तु निरीक्षक में निम्नलिखित दृश्य पेश करता है:

मुझे पता है, मैं कैसे इस तरह से अपने ही मॉड्यूल लिख सकते हैं चाहता हूँ, कि इस तरह की अच्छा दृश्य तब उत्पन्न होता है जब मैं अपने कार्यों को स्पाइडर में कॉल करता हूं।

Answer 1

अपने दस्तावेज़ numpy एक के रूप में के रूप में अच्छी तरह से प्रस्तुत करने के लिए के लिए, आप NumpyDoc मानक का पालन करने की जरूरत है। मान लीजिए आप एक समारोह इस तरह दो तर्कों func कहा जाता है:

def func(arg1, arg2): 
    return True 

इसे करने के लिए प्रलेखन जोड़ने के लिए आप अपनी परिभाषा (अजगर दुनिया में कहा जाता docstring) के नीचे एक बहु स्ट्रिंग लिखने के लिए की जरूरत है, इस

की तरह

def func(arg1, arg2): 
    """Summary line. 

    Extended description of function. 

    Parameters 
    ---------- 
    arg1 : int 
     Description of arg1 
    arg2 : str 
     Description of arg2 

    Returns 
    ------- 
    bool 
     Description of return value 

    Examples 
    -------- 
    >>> func(1, "a") 
    True 
    """ 
    return True 

स्पाइडर क्या करता है यह है कि यह सादा पाठ विवरण, पार्स और इसे HTML के रूप में प्रस्तुत करता है और अंत में इसे ऑब्जेक्ट इंस्पेक्टर में दिखाता है।

यह देखने के लिए आप बस अपने कोड में कहीं और func फोन और Ctrl दबाने की जरूरत + मैं इसके बगल में, इस तरह:

func<Ctrl+i>(1, "a") 

यह भी स्वचालित रूप से दिखाया गया है जब आप एक लिखने func के बगल में बाएं कोष्ठक।

Answer 2

आप अपने अजगर परियोजना (या फाइल) पहले से ही नहीं एक अन्य शैली के साथ दस्तावेज (reStructuredText या Epytext रूप में) या दस्तावेज, आप उत्पन्न कर सकते हैं/NumpyDoc शैली में docstrings परिवर्तित Pyment का उपयोग कर है, तो:

pyment -o numpydoc /my/python/project 

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

एक बार अपनी परियोजना Numpydoc शैली का उपयोग प्रलेखित है, तो आप Sphinx extension का उपयोग अपने अच्छा पठनीय NumpyDoc शैली प्रलेखन उत्पन्न करने के लिए कर सकते हैं!