Python कोड का प्रलेखन कैसे करें

यदि आप Python की शुरुआत कर रहे हैं और अधिक सीखना चाहते हैं, तो DataCamp का Intermediate Python कोर्स लें।

अपने प्रोजेक्ट का प्रलेखन क्यों प्रासंगिक है

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

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

Python के जाने-माने रचयिता का कथन है कि Code is more often read than written. यह कथन इस बात पर जोर देता है कि जब अन्य लोग आपके कोड या प्रोजेक्ट को लागू करते हैं तो डॉक्यूमेंटेशन कितना महत्वपूर्ण होता है।

कल्पना कीजिए कि आप XYZ कंपनी में नौकरी छोड़ने की अवधि में हैं और आपके मैनेजर चाहते हैं कि आप वह प्रोजेक्ट अपने सहकर्मी को सौंप दें। आप उन्हें KT (knowledge transfer) दे सकते हैं, पर यदि आपका सहकर्मी प्रोजेक्ट का कोई कोड सफलतापूर्वक चलाने में विफल रहता है तो? कई कारण हो सकते हैं—शायद आपके कोड के लिए जो बाइनरी आवश्यक हैं, वे मौजूदा OS की बाइनरी से मेल नहीं खाते।

डॉक्यूमेंटेशन वास्तव में है क्या?

डॉक्यूमेंटेशन कई घटकों का समूह होता है। इसे इन घटकों के इर्द-गिर्द सुव्यवस्थित होना चाहिए और इन्हीं का पालन करना चाहिए ताकि इसे उचित डॉक्यूमेंटेशन माना जा सके।

सार रूप में, ये घटक हैं:

• यह सुनिश्चित करना कि आपके प्रोजेक्ट का कोडबेस अच्छे से कमेंटेड हो।

• यह Python के PEP-8 कोडिंग मानकों का पालन करे।

• ठोस ट्यूटोरियल्स जो बताएं कि प्रोजेक्ट कैसे बनाया गया, खासकर जब वह सीखने के उद्देश्य से विकसित ओपन-सोर्स प्रोजेक्ट हो।

• आवश्यक पैकेज और मॉड्यूल कैसे इंस्टॉल करें, इस पर गाइड; यदि प्रोजेक्ट में हार्डवेयर भी शामिल है तो तकनीकी स्पेसिफिकेशन शीट। उदाहरण के लिए, anaconda, TensorFlow, Keras आदि कैसे इंस्टॉल करें।

• प्रत्येक चरण पर प्रोजेक्ट की प्रगति पर कई चर्चाएं, जिनसे सॉफ्टवेयर के सफल क्रियान्वयन तक पहुँचा जा सका।

• डेवलपमेंट चरण में उपयोग किए गए टेक्नोलॉजी स्टैक का तकनीकी विवरण देने वाली संदर्भ सामग्री।

• प्रोजेक्ट या सॉफ्टवेयर समाधान की आर्किटेक्चरल डिजाइन।

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

व्यापक डॉक्यूमेंटेशन का एक उदाहरण, जिसमें हमारे द्वारा चर्चा किए गए अधिकांश घटक मौजूद हों, नीचे दिखाए गए जैसा हो सकता है:

अक्सर बहुत से लोग commenting और documenting को लेकर भ्रमित हो जाते हैं और उन्हें समान समझते हैं। कमेंटिंग का उपयोग आपके कोड को उपयोगकर्ता, मेंटेनर, और स्वयं आपके लिए भविष्य संदर्भ हेतु समझाने के लिए किया जाता है। कमेंटिंग केवल कोड-स्तर पर काम करती है और इसे डॉक्यूमेंटेशन का एक उपसमुच्चय माना जा सकता है। कमेंट्स पाठक की इन बातों में मदद करते हैं:

• आपके कोड को समझने में,
• उसे स्वव्याख्यात्मक बनाने में, और
• उसके उद्देश्य और डिजाइन को समझने में।

ध्यान देने वाली बात है कि Python PEP-8 कोडिंग मानकों का पालन करता है, इसलिए कमेंट्स को भी उन्हीं मानकों का पालन करना चाहिए। आधिकारिक Python डॉक्यूमेंटेशन बताता है कि लंबे मुक्त-प्रवाह वाले पाठ (docstrings या कमेंट्स) की पंक्ति लंबाई 72 वर्णों तक सीमित होनी चाहिए।

यह जाँचने के लिए कि आपका कोड PEP-8 मानकों का पालन कर रहा है या नहीं, आप Python के pylint मॉड्यूल का उपयोग कर सकते हैं। इस मॉड्यूल से आप कमेंट्स और अन्य सभी कोड लाइनों के लिए वर्ण सीमा संशोधित कर सकते हैं।

आइए कुछ उदाहरण देखें।

• मॉड्यूल इम्पोर्ट का विवरण

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• वेरिएबल परिभाषा का विवरण

n_classes = 10 # MNIST total classes (0-9 digits)

कमेंटिंग को अधिक गहराई से समझने और उसके do's & don'ts जानने के लिए यह उपयोगी पोस्ट देखें।

अब सीखते हैं कि docstrings आपके प्रोजेक्ट के कोडबेस के प्रलेखन में कैसे मदद कर सकते हैं।

Python कोड के प्रलेखन के लिए Docstrings

Python Docstring एक डॉक्यूमेंटेशन स्ट्रिंग है, जो string literal के रूप में क्लास, मॉड्यूल, फ़ंक्शन या मेथड की परिभाषा में आती है और पहली स्टेटमेंट के रूप में लिखी जाती है। Docstrings किसी भी Python ऑब्जेक्ट के doc एट्रिब्यूट (__doc__) के जरिए सुलभ होती हैं, और बिल्ट-इन help() फ़ंक्शन के साथ भी काम आती हैं।

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

Docstring लिखने के दो रूप हैं: एक-लाइन Docstrings और मल्टीलाइन Docstrings। डेटा वैज्ञानिक/प्रोग्रामर अपनी परियोजनाओं में इन्हीं का उपयोग करते हैं।

• one-line Docstrings वे होती हैं जो एक ही पंक्ति में समा जाती हैं। आप ट्रिपल सिंगल या ट्रिपल डबल कोट्स का उपयोग कर सकते हैं; ओपनिंग और क्लोज़िंग कोट्स समान होने चाहिए। एक-लाइन Docstrings में क्लोज़िंग कोट्स उसी पंक्ति में होते हैं जहाँ ओपनिंग कोट्स होते हैं। मानक प्रथा ट्रिपल-डबल कोट्स का उपयोग करना है।

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Multi-line Docstrings में भी वही स्ट्रिंग लिटरल होता है जैसा एक-लाइन Docstrings में, लेकिन इसके बाद एक खाली पंक्ति और फिर वर्णनात्मक टेक्स्ट आता है।

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

ऊपर दी गई तालिका में से, आइए Pydoc को एक docstring फ़ॉर्मैट के रूप में चुनें और इसे थोड़ा समझें।

जैसा कि आपने सीखा, docstrings बिल्ट-इन Python के __doc__ एट्रिब्यूट और help() फ़ंक्शन के जरिए उपलब्ध हैं। आप Pydoc नामक बिल्ट-इन मॉड्यूल का भी उपयोग कर सकते हैं, जो doc एट्रिब्यूट और help फ़ंक्शन की तुलना में अपनी विशेषताओं और क्षमताओं के मामले में काफी अलग है।

Pydoc एक ऐसा टूल है जो तब काम आता है जब आप कोड अपने सहकर्मियों के साथ साझा करना चाहते हैं या उसे ओपन-सोर्स करना चाहते हैं—ऐसी स्थिति में आपका लक्षित दर्शक वर्ग और व्यापक होगा। यह आपके Python डॉक्यूमेंटेशन से वेब पृष्ठ बना सकता है और एक वेब सर्वर भी चला सकता है।

देखते हैं यह कैसे काम करता है।

Pydoc मॉड्यूल चलाने का सबसे आसान और सुविधाजनक तरीका है इसे स्क्रिप्ट के रूप में चलाना। इसे jupyter lab सेल के अंदर चलाने के लिए आप विस्मयादिबोधक चिन्ह (!) का उपयोग करेंगे।

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

यदि आप ऊपर के आउटपुट पर ध्यान दें, तो Pydoc का पहला उपयोग किसी फ़ंक्शन, मॉड्यूल, क्लास आदि पर टेक्स्ट डॉक्यूमेंटेशन दिखाना है—आइए देखें कि आप इसे help फ़ंक्शन से बेहतर कैसे उपयोग कर सकते हैं।

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

अब, आइए glob का डॉक्यूमेंटेशन help फ़ंक्शन से निकालें।

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

जैसा कि आप देख सकते हैं, यह name error देता है क्योंकि glob परिभाषित नहीं है। अतः help फ़ंक्शन से डॉक्यूमेंटेशन निकालने के लिए आपको पहले मॉड्यूल इम्पोर्ट करना होगा, जबकि Pydoc में यह ज़रूरी नहीं है।

अब Pydoc मॉड्यूल की सबसे दिलचस्प सुविधा देखें—Pydoc को वेब सेवा के रूप में चलाना।

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

!python -m pydoc -b

^C

जैसे ही आप ऊपर वाला सेल चलाएँगे, एक नया विंडो किसी मनमाने पोर्ट नंबर पर खुलेगा, और वेब ब्राउज़र नीचे दिखाए गए जैसा दिखाई देगा।

आइए h5py मॉड्यूल के डॉक्यूमेंटेशन पर नज़र डालें, जो न्यूरल नेटवर्क आर्किटेक्चर के वज़न संग्रहीत करने के लिए प्रयुक्त फ़ाइल फ़ॉर्मैट है।

Python प्रोजेक्ट्स का प्रलेखन करते समय आवश्यक बातें

लक्ष्य, दृष्टि और प्रोजेक्ट उद्देश्य कुछ भी हो, हर प्रोजेक्ट का डॉक्यूमेंटेशन कमोबेश एक जैसा रहता है। प्रोजेक्ट निम्नलिखित श्रेणियों में आ सकता है:

• निजी (पर्सनल) प्रोजेक्ट: पोर्टफोलियो बनाने के लिए या फ्रीलांसर के रूप में GitHub रिपॉज़िटरी मेंटेन करने हेतु।

• सहयोगी (टीम) प्रोजेक्ट्स: आपके संगठन में चल रहा कोई प्रोजेक्ट या Kaggle प्रतियोगिता पर काम।

• ओपन-सोर्स प्रोजेक्ट्स: व्यापक दर्शकों के साथ साझा करने पर केंद्रित। इसमें सहयोग, योगदान और लंबे समय तक कोडबेस व डॉक्यूमेंटेशन की मेंटेनबिलिटी अपेक्षित होती है।

हालाँकि इन तीनों श्रेणियों की दृष्टि भिन्न है, पर डॉक्यूमेंटेशन टेम्पलेट सभी प्रकार के प्रोजेक्ट्स में साझा किया जा सकता है।

मान लीजिए आप एक ओपन-सोर्स प्रोजेक्ट पर काम कर रहे हैं और उसके लिए GitHub रिपॉज़िटरी बनानी है, जिसमें विस्तृत और नियमित रूप से अपडेट किया गया डॉक्यूमेंटेशन होना चाहिए—ध्यान रखने योग्य आवश्यक बिंदु ये हैं:

• Requirements फ़ाइल: लेखक अक्सर इसे भूल जाते हैं, लेकिन यह बहुत महत्वपूर्ण है। इससे उपयोगकर्ता आपका कोड जल्दी पुनरुत्पादित कर पाते हैं। यह आमतौर पर एक टेक्स्ट फ़ाइल होती है जिसमें प्रोजेक्ट में उपयोग किए गए सभी पैकेज, मॉड्यूल और उनके वर्ज़न होते हैं। Requirements को Readme में भी लिखा जा सकता है, लेकिन अलग फ़ाइल होना बेहतर है क्योंकि उपयोगकर्ता उसे pip कमांड से चलाकर सभी डिपेंडेंसी अपने सिस्टम पर इंस्टॉल कर सकता है।

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

• कैसे सहयोग करें: खासकर ओपन-सोर्स प्रोजेक्ट्स में यह महत्वपूर्ण है। इसमें बताया जाना चाहिए कि नए सहयोगी प्रोजेक्ट में कैसे योगदान कर सकते हैं—नई फीचर्स विकसित करना, ज्ञात बग्स ठीक करना, डॉक्यूमेंटेशन जोड़ना, नए टेस्ट जोड़ना या इश्यू रिपोर्ट करना। सहयोगी इसी प्रोजेक्ट का v2.0 भी जारी कर सकते हैं और उसे नई ऊँचाइयों पर ले जा सकते हैं।

• लाइसेंस: एक सादा टेक्स्ट फ़ाइल जो बताती है कि आपका प्रोजेक्ट किस लाइसेंस का उपयोग कर रहा है—जैसे Boost, Apache, MIT आदि। यह उपयोगकर्ता को बताता है कि प्रोजेक्ट व्यावसायिक रूप से मुफ़्त है या किस सीमा तक उपयोग योग्य है।

• कार्य आवंटन: यदि आप Kaggle जैसे साझा प्रोजेक्ट पर काम कर रहे हैं, तो आप प्रत्येक सदस्य को सौंपे गए कार्य और उनकी प्रगति का स्तर परिभाषित कर सकते हैं। इससे प्रोजेक्ट की समग्र प्रगति पर नज़र रखना आसान होता है।

• फ़्रेमवर्क पुन:उपयोग: Kaggle जैसे साझा प्रोजेक्ट में इसका अहम रोल है, जहाँ टीममेट्स आपके द्वारा बनाए गए घटकों का पुन:उपयोग कर सकते हैं, जिससे काफी समय बचता है। उदाहरण के लिए, डेटा प्रीप्रोसेसिंग पाइपलाइन, डेटा क्रॉस-वैलिडेशन स्क्रिप्ट आदि।

बेहद अनुशंसित, सुव्यवस्थित डॉक्यूमेंटेशन का एक उत्कृष्ट उदाहरण—यह देखने के लिए कि एक ओपन-सोर्स प्रोजेक्ट कैसा दिखना चाहिए—huggingface transformers की GitHub रिपॉज़िटरी देखें।

निष्कर्ष

ट्यूटोरियल पूरा करने पर बधाई।

आपके लिए एक अच्छा अभ्यास यह होगा कि Pydoc मॉड्यूल को थोड़ा और एक्सप्लोर करें और अन्य Python docstring फ़ॉर्मैट्स जैसे Epydoc और Google docstrings को देखें और जानें कि वे एक-दूसरे से कैसे भिन्न हैं।

कृपया इस ट्यूटोरियल से संबंधित कोई भी प्रश्न नीचे टिप्पणी अनुभाग में पूछें।

संदर्भ:

• Python में Docstrings

यदि आप Python की शुरुआत कर रहे हैं और अधिक सीखना चाहते हैं, तो DataCamp का Intermediate Python कोर्स लें।