Tutorial Docstring Python: Contoh & Format untuk Pydoc, Numpy, Sphinx Doc Strings

Jika Anda baru mulai belajar Python dan ingin mempelajari lebih lanjut, ikuti kursus Introduction to Data Science in Python dari DataCamp.

Latih Docstring di Python dengan latihan praktik ini.

Apa itu Docstring Python? 

String dokumentasi Python, yang biasa disebut docstring, adalah literal string yang digunakan dalam definisi kelas, modul, fungsi, atau metode. Docstring dapat diakses dari atribut doc (__doc__) untuk objek Python apa pun dan juga dengan fungsi bawaan help(). Docstring suatu objek ditentukan dengan menyertakan konstanta string sebagai pernyataan pertama dalam definisi objek tersebut.

Berbeda dengan komentar biasa yang menjelaskan baris-baris kode individual, docstring memberikan deskripsi tingkat tinggi tentang apa yang dilakukan sebuah fungsi, kelas, atau modul. Docstring yang ditulis dengan baik meningkatkan keterbacaan kode, kemudahan pemeliharaan, dan kolaborasi, sehingga menjadi praktik terbaik untuk mendokumentasikan kode Python Anda sebagai pengembang Python.

Docstring membantu Anda memahami kapabilitas sebuah modul atau fungsi. Misalnya, katakanlah Anda memasang pustaka scikit-learn dan ingin mengetahui semua tentang paket sklearn seperti deskripsi, modul paket, dan sebagainya; Anda bisa menggunakan fungsi help untuk mendapatkan semua informasinya.

Yuk, impor paketnya terlebih dahulu.

import sklearn

help(sklearn)

Anda akan melihat keluaran yang mirip dengan berikut ini:

Docstring Python vs. Komentar

Docstring secara konsep mirip dengan komentar, tetapi merupakan versi komentar yang ditingkatkan, lebih logis, dan lebih berguna. Docstring berfungsi sebagai dokumentasi untuk kelas, modul, dan paket.

Di sisi lain, komentar terutama digunakan untuk menjelaskan bagian kode yang tidak jelas dan berguna untuk mencatat perbaikan bug dan tugas yang perlu dikerjakan.

Docstring direpresentasikan dengan tanda kutip pembuka & penutup, sedangkan komentar diawali dengan # di awal.

Perlu dicatat bahwa komentar tidak dapat diakses dengan atribut bawaan doc dan fungsi help. Mari lihat apa yang terjadi jika Anda mencobanya:

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Ada beberapa cara menulis atau menggunakan Docstring, yaitu one-line docstring dan multi-line docstring. Mari pelajari satu per satu.

Docstring Satu Baris

Docstring satu baris adalah deskripsi singkat yang muat dalam satu baris. Docstring ditulis dengan tiga tanda kutip (''' atau """), dan tanda kutip penutup harus berada pada baris yang sama.

Walaupun tiga tanda kutip tunggal maupun ganda bisa digunakan, konvensi standar di Python adalah menggunakan tiga tanda kutip ganda (""").

Berikut contohnya: 

def square(a):
    """Returns the square of the given number."""
    return a ** 2  # Corrected exponentiation

# Accessing the docstring
print(square.__doc__)

Keluaran:

Returns the square of the given number.

Anda juga dapat mengambil dokumentasi ini menggunakan fungsi help() Python:

help(square)

Keluaran:

Help on function square in module __main__:

square(a)
    Returns the square of the given number.

Docstring Multi Baris

Docstring multi baris juga berisi baris ringkasan seperti pada docstring satu baris, tetapi diikuti satu baris kosong dan teks deskriptif.

Format umum untuk menulis Docstring multi baris adalah sebagai berikut:

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

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Mari lihat contoh yang menunjukkan bagaimana string multi baris dapat digunakan secara lebih rinci:

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Anda dapat melihat di atas bahwa baris ringkasan berada pada satu baris dan dipisahkan dari konten lain oleh satu baris kosong. Konvensi ini perlu diikuti karena berguna untuk alat pengindeksan otomatis.

Docstring Bawaan Python

Mari lihat Docstring bawaan Python.

Semua fungsi, kelas, dan metode bawaan memiliki deskripsi manusiawi yang melekat padanya. Anda dapat mengaksesnya dengan dua cara.

• atribut doc
• fungsi help

Anda akan melihat bahwa keluaran fungsi help lebih panjang daripada atribut __doc__.

Sebagai contoh:

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

Demikian pula, Anda dapat menggunakan fungsi help:

help(math)

Docstring Python dalam Kelas

Dalam definisi kelas, docstring dapat digunakan untuk memberikan dokumentasi bagi keseluruhan kelas. Biasanya ditempatkan tepat setelah definisi kelas dan ditulis dalam tiga tanda kutip ("""). Contoh:

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Docstring dapat diakses menggunakan atribut __doc__ dari kelas atau metode. Misalnya, Anda dapat mengakses docstring untuk MyClass menggunakan MyClass.__doc__.

Sekarang mari lihat beberapa Format Docstring populer dan memahaminya lebih detail.

Format Docstring Python

Ada banyak format Docstring yang tersedia, tetapi sebaiknya gunakan format yang mudah dikenali oleh parser Docstring dan juga oleh sesama Data Scientist/programmer. Tidak ada aturan baku untuk memilih format Docstring, namun konsistensi menggunakan format yang sama di seluruh proyek itu penting. Selain itu, lebih baik menggunakan jenis pemformatan yang sebagian besar didukung oleh Sphinx.

Format yang paling umum digunakan tercantum di bawah ini.

Mungkin ada berbagai string dokumentasi yang tersedia. Anda tidak perlu khawatir harus mempelajari semuanya dari nol. Format semua string dokumentasi hampir mirip. Polanya serupa, hanya ada perbedaan kecil pada tiap format. Anda akan melihat contoh format populer untuk string dokumentasi beserta penggunaannya.

Pertama, Anda akan melihat Sphinx Style secara rinci, lalu Anda dapat dengan mudah mengikuti format lainnya.

Gaya Sphinx

Sphinx adalah gaya yang mudah dan tradisional, bersifat verbose, dan awalnya dibuat khusus untuk Dokumentasi Python. Sphinx menggunakan reStructuredText, yang penggunaannya mirip dengan Markdown.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

Sphinx menggunakan keyword(reserved word) sebagaimana sebagian besar bahasa pemrograman. Namun secara khusus disebut role di Sphinx. Pada kode di atas, Sphinx memiliki param sebagai role, dan type adalah role yang merupakan tipe data Sphinx untuk param. Role type bersifat opsional, tetapi param wajib. Role pengembalian mendokumentasikan objek yang dikembalikan. Ini berbeda dari role param. Role pengembalian tidak bergantung pada rtype dan sebaliknya. rtype adalah tipe objek yang dikembalikan dari fungsi yang diberikan.

Gaya Google

Gaya Google lebih mudah dan lebih intuitif digunakan. Gaya ini cocok untuk dokumentasi yang lebih singkat. Diperlukan konfigurasi berkas Python untuk memulai, yaitu menambahkan sphinx.ext.napoleon atau sphinxcontrib.napoleon ke daftar extensions di conf.py.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

Gaya Google lebih baik daripada gaya Sphinx. Namun ada kekurangan, yaitu pada kode di atas, deskripsi multi baris untuk distance akan terlihat berantakan. Itulah mengapa Numpy dapat digunakan untuk dokumentasi yang lebih panjang.

Gaya Numpy

Gaya Numpy memiliki banyak detail dalam dokumentasi. Gaya ini lebih verbose daripada dokumentasi lainnya, tetapi merupakan pilihan yang sangat baik jika Anda ingin membuat dokumentasi mendetail, yaitu dokumentasi ekstensif untuk semua fungsi dan parameter.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

Contoh di atas lebih verbose daripada dokumentasi lainnya. Contoh ini lebih panjang dan sebaiknya digunakan untuk dokumentasi yang panjang dan mendetail.

PyDoc

Seperti yang Anda ketahui, docstring dapat diakses melalui atribut bawaan Python __doc__ dan fungsi help(). Anda juga bisa memanfaatkan modul bawaan bernama Pydoc, yang sangat berbeda dari sisi fitur & fungsionalitas dibandingkan dengan atribut doc dan fungsi help.

Pydoc adalah alat yang bermanfaat saat Anda ingin berbagi kode dengan rekan kerja atau menjadikannya open-source, di mana Anda menargetkan audiens yang jauh lebih luas. Pydoc dapat menghasilkan halaman web dari dokumentasi Python Anda dan juga dapat menjalankan server web.

Mari lihat cara kerjanya.

Cara termudah dan paling nyaman untuk menjalankan modul Pydoc adalah menjalankannya sebagai skrip. Untuk menjalankannya di dalam sel jupyter lab, Anda akan menggunakan karakter tanda seru (!).

• Pydoc sebagai modul

!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.

Jika Anda melihat keluaran di atas, penggunaan pertama Pydoc adalah menampilkan dokumentasi teks pada fungsi, modul, kelas, dan sebagainya, jadi mari lihat bagaimana Anda bisa memanfaatkannya dengan lebih baik daripada fungsi 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

Sekarang, mari ambil dokumentasi glob menggunakan fungsi help.

help(glob)

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

NameError                                 Traceback (most recent call last)

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


NameError: name 'glob' is not defined

Nah, seperti yang Anda lihat, muncul name error karena glob belum didefinisikan. Jadi agar dapat menggunakan fungsi help untuk mengambil dokumentasi, Anda harus terlebih dahulu mengimpor modul tersebut, yang tidak diperlukan pada Pydoc.

• Pydoc sebagai layanan web

Mari jelajahi fitur Pydoc yang paling menarik, yaitu menjalankan Pydoc sebagai layanan web.

Untuk melakukan ini, Anda cukup menjalankan Pydoc sebagai skrip dengan argumen -b yang akan memulai server HTTP pada port kosong acak dan membuka browser web untuk menjelajahi dokumentasi secara interaktif. Ini bermanfaat terutama ketika Anda memiliki berbagai layanan lain yang berjalan di sistem dan Anda tidak ingat port mana yang sedang menganggur.

!python -m pydoc -b

^C

Saat Anda menjalankan sel di atas, jendela baru akan terbuka pada nomor port acak, dan browser web akan terlihat mirip dengan gambar di bawah.

Mari lihat dokumentasi modul h5py, yaitu format berkas yang digunakan untuk menyimpan bobot arsitektur jaringan saraf.

Perbandingan format docstring 

Pada tabel di bawah, Anda dapat melihat perbandingan berbagai jenis format docstring yang telah disebutkan di atas: 

• Gaya Sphinx: Sering digunakan di proyek besar yang membutuhkan dokumentasi komprehensif. Terintegrasi baik dengan generator dokumentasi Sphinx.
• Gaya Google: Ideal untuk proyek yang mengutamakan kesederhanaan dan keterbacaan, terutama di organisasi yang menggunakan panduan gaya Google.
• Gaya NumPy: Paling cocok untuk proyek yang memerlukan dokumentasi rinci dan ekstensif, umum di data science dan komputasi ilmiah.
• PyDoc: Berguna untuk menghasilkan dokumentasi teks dan HTML, tetapi tidak memiliki format terstruktur seperti yang lain.

Kesimpulan

Selamat telah menyelesaikan tutorial docstring di Python.

Tutorial ini berfokus terutama untuk membantu Anda memulai dengan docstring dengan membahas topik-topik esensial. Namun, Docstring adalah topik yang luas, dan beberapa konsep mungkin belum dibahas. Jika Anda ingin belajar lebih lanjut, lihat tutorial string Python kami dan kursus tentang menulis fungsi di Python.

Jika Anda baru mulai belajar Python dan ingin mempelajari lebih lanjut, ikuti kursus Introduction to Data Science in Python dari DataCamp. Anda juga dapat mengambil salah satu jalur karier Python kami dan memulai perjalanan menjadi Pengembang Python atau Data Scientist dengan Python.