डॉक्यूमेंटेशन

Python पैकेज विकसित करना

James Fulton

Climate informatics researcher

डॉक्यूमेंटेशन क्यों शामिल करें?

  • आपके यूज़र्स को आपका कोड इस्तेमाल करने में मदद मिलती है
  • हर एक का डॉक्यूमेंट करें
    • Function
    • Class
    • Class method
import numpy as np
help(np.sum)

...
sum(a, axis=None, dtype=None, out=None)
    Sum of array elements over a given axis.

    Parameters
    ----------
    a : array_like
        Elements to sum.
    axis : None or int or tuple of ints, optional
        Axis or axes along which a sum is performed.  
        The default, axis=None, will sum all of the 
        elements of the input array.
...
Python पैकेज विकसित करना

डॉक्यूमेंटेशन क्यों शामिल करें?

  • आपके यूज़र्स को आपका कोड इस्तेमाल करने में मदद मिलती है
  • हर एक का डॉक्यूमेंट करें
    • Function
    • Class
    • Class method
import numpy as np
help(np.array)

...
    array(object, dtype=None, copy=True)

    Create an array.

    Parameters
    ----------
    object : array_like
        An array, any object exposing the array 
        interface ...
    dtype : data-type, optional
        The desired data-type for the array. 
    copy : bool, optional
        If true (default), then the object is copied.
...
Python पैकेज विकसित करना

डॉक्यूमेंटेशन क्यों शामिल करें?

  • आपके यूज़र्स को आपका कोड इस्तेमाल करने में मदद मिलती है
  • हर एक का डॉक्यूमेंट करें
    • Function
    • Class
    • Class method
import numpy as np
x = np.array([1,2,3,4])
help(x.mean)

...
mean(...) method of numpy.ndarray instance
    a.mean(axis=None, dtype=None, out=None)

    Returns the average of the array elements 
    along given axis.

    Refer to `numpy.mean` for full documentation.
...
Python पैकेज विकसित करना

फंक्शन डॉक्यूमेंटेशन

def count_words(filepath, words_list):

    """ ... """
Python पैकेज विकसित करना

फंक्शन डॉक्यूमेंटेशन

def count_words(filepath, words_list):

    """इन शब्दों के कुल बार आने की गिनती करें।"""
Python पैकेज विकसित करना

फंक्शन डॉक्यूमेंटेशन

def count_words(filepath, words_list):

    """इन शब्दों के कुल बार आने की गिनती करें।

    दी गई लोकेशन पर टेक्स्ट फ़ाइल पर यह गिनती की जाती है।
    """
Python पैकेज विकसित करना

फंक्शन डॉक्यूमेंटेशन

def count_words(filepath, words_list):

    """इन शब्दों के कुल बार आने की गिनती करें।

    दी गई लोकेशन पर टेक्स्ट फ़ाइल पर यह गिनती की जाती है।

    [समझाएँ कि filepath और words_list क्या हैं]

    [क्या रिटर्न होता है]
    """
Python पैकेज विकसित करना

डॉक्यूमेंटेशन स्टाइल

Google डॉक्यूमेंटेशन स्टाइल

"""Summary line.

Extended description of function.

Args:
    arg1 (int): Description of arg1
    arg2 (str): Description of arg2

NumPy स्टाइल

    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1 ...

    Returns
    ----------
    numpy.ndarray

reStructured text स्टाइल

    """Summary line.

    Extended description of function.

    :param arg1: Description of arg1
    :type arg1: int
    :param arg2: Description of arg2
    :type arg2: str

Epytext स्टाइल

"""Summary line.

  Extended description of function.

  @type arg1: int
  @param arg1:  Description of arg1
  @type arg2: str
  @param arg2: Description of arg2
Python पैकेज विकसित करना

NumPy डॉक्यूमेंटेशन स्टाइल

वैज्ञानिक Python पैकेजों में लोकप्रिय, जैसे

  • numpy
  • scipy
  • pandas
  • sklearn
  • matplotlib
  • dask
  • आदि
Python पैकेज विकसित करना

NumPy डॉक्यूमेंटेशन स्टाइल

import scipy
help(scipy.percentile)

percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
    Compute the q-th percentile of the data along the specified axis.

    Returns the q-th percentile(s) of the array elements.


    Parameters
    ----------

    a : array_like

        Input array or object that can be converted to an array.

Other types include - int, float, bool, str, dict, numpy.array, etc.

Python पैकेज विकसित करना

NumPy डॉक्यूमेंटेशन स्टाइल

import scipy
help(scipy.percentile)

percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
    ...
    Parameters
    ----------
    ...
    axis : {int, tuple of int, None}
    ...
    interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
  • अगर उपयुक्त हो तो पैरामीटर के लिए एक से ज़्यादा टाइप सूचीबद्ध करें
  • जब केवल कुछ ही वैध विकल्प हों तो स्वीकृत मान सूचीबद्ध करें
Python पैकेज विकसित करना

NumPy डॉक्यूमेंटेशन स्टाइल

import scipy
help(scipy.percentile)

percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
    ...
    Returns
    -------
    percentile : scalar or ndarray
        If `q` is a single percentile and `axis=None`, then the result
        is a scalar. If multiple percentiles are given, first axis of
        the result corresponds to the percentiles...
    ...
Python पैकेज विकसित करना

NumPy डॉक्यूमेंटेशन स्टाइल

अन्य सेक्शन

  • Raises
  • See Also
  • Notes
  • References
  • Examples
1 https://numpydoc.readthedocs.io/en/latest/format.html
Python पैकेज विकसित करना

डॉक्यूमेंटेशन टेम्प्लेट और स्टाइल ट्रांसलेशन

  • pyment से docstrings जनरेट कर सकते हैं
  • टर्मिनल से चलाएँ
  • किसी भी डॉक्यूमेंटेशन स्टाइल से
    • Google
    • Numpydoc
    • reST (यानी reStructured-text)
    • Javadoc (यानी epytext)
  • एक स्टाइल से दूसरे में डॉक्यूमेंटेशन बदलें
Python पैकेज विकसित करना

डॉक्यूमेंटेशन टेम्प्लेट और स्टाइल ट्रांसलेशन

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    # Open the text file
    ...
    return n
  • -w - फ़ाइल ओवरराइट करें
  • -o numpydoc - आउटपुट NumPy स्टाइल में
Python पैकेज विकसित करना

डॉक्यूमेंटेशन टेम्प्लेट और स्टाइल ट्रांसलेशन

pyment -w -o numpydoc textanalysis.py

def count_words(filepath, words_list):
    """

    Parameters
    ----------
    filepath :

    words_list :


    Returns
    -------
    type
    """
Python पैकेज विकसित करना

Google स्टाइल में ट्रांसलेट करें

pyment -w -o google textanalysis.py

def count_words(filepath, words_list):
    """इन शब्दों के कुल बार आने की गिनती करें।

    दी गई लोकेशन पर टेक्स्ट फ़ाइल पर यह गिनती की जाती है।

    Parameters
    ----------
    filepath : str
        Path to text file.
    words_list : list of str
        Count the total number of appearances of these words.

    Returns
    -------

    """
Python पैकेज विकसित करना

Google स्टाइल में ट्रांसलेट करें

pyment -w -o google textanalysis.py

def count_words(filepath, words_list):
    """इन शब्दों के कुल बार आने की गिनती करें।

    दी गई लोकेशन पर टेक्स्ट फ़ाइल पर यह गिनती की जाती है।

    Args:
      filepath(str): Path to text file.
      words_list(list of str): Count the total number of appearances of these words.

    Returns:


    """
Python पैकेज विकसित करना

पैकेज, सबपैकेज और मॉड्यूल डॉक्यूमेंटेशन

mysklearn/__init__.py

"""
Linear regression for Python
============================

mysklearn is a complete package for implmenting
linear regression in python. 
"""

mysklearn/preprocessing/__init__.py

"""
स्टैंडर्ड प्रीप्रोसेसिंग ऑपरेशंस के लिए एक सबपैकेज।
"""

 

mysklearn/preprocessing/normalize.py

"""
डेटा नॉर्मलाइज़ करने के लिए एक मॉड्यूल।
"""
Python पैकेज विकसित करना

अभ्यास करते हैं!

Python पैकेज विकसित करना

Preparing Video For Download...