Dokumentasi yang baik menjelaskan kontrak sebuah fungsi: masukan, hasil, dan error yang mungkin muncul. Lampiran ini menghubungkan docstring dengan contoh yang dapat diuji serta halaman dokumentasi yang dapat dihasilkan.

Tujuan Penggunaan

Gunakan lampiran ini saat sebuah fungsi mulai dipakai kembali olehmu atau orang lain. Setelah praktik, kamu dapat menulis docstring yang sesuai code, menguji contoh pemakaiannya, dan menghasilkan dokumentasi HTML sederhana.

Persiapan

Pelajari fungsi, exception, serta modul pada Bab 11, 15, dan 17. Siapkan folder proyek tersendiri. pydoc dan doctest tersedia bersama Python; pdoc dan Sphinx adalah tambahan opsional yang dipasang dalam venv. Contoh kelas dapat dibaca kembali setelah kamu mempelajari objek dan kelas.

Panduan dan Contoh

Menulis kontrak yang sesuai dengan fungsi

Docstring adalah literal string yang menjadi pernyataan pertama modul, fungsi, kelas, atau metode. Komentar biasa tidak menjadi __doc__. Gunakan tiga tanda kutip ganda untuk gaya yang konsisten. Letakkan ringkasan pada baris pertama, lalu baris kosong sebelum rincian.

Simpan contoh berikut sebagai geometri.py. Fungsi menerima int atau float yang berhingga dan nonnegatif. Nol diperbolehkan; boolean ditolak agar True tidak dianggap panjang sisi. Hasil perkalian mengikuti tipe angkanya. Input keliru memicu exception, bukan menghasilkan None.

"""Fungsi geometri sederhana untuk latihan dokumentasi."""

import math


def luas_persegi(sisi):
    """Hitung luas dari sisi yang berhingga dan nonnegatif.

    Args:
        sisi (int | float): Panjang sisi; bukan bool.

    Returns:
        int | float: Hasil sisi dikalikan dengan sisi.

    Raises:
        TypeError: Jika tipe sisi bukan int atau float.
        ValueError: Jika sisi negatif atau tidak berhingga.

    Examples:
        >>> luas_persegi(5)
        25
        >>> luas_persegi(2.5)
        6.25
        >>> luas_persegi(0)
        0
    """
    if type(sisi) not in (int, float):
        raise TypeError("Sisi harus int atau float.")
    if sisi < 0 or (
        isinstance(sisi, float) and not math.isfinite(sisi)
    ):
        raise ValueError("Sisi harus berhingga dan nonnegatif.")
    return sisi * sisi


if __name__ == "__main__":
    print(luas_persegi(5))
    print(luas_persegi(2.5))
    print(luas_persegi(0))

25
6.25
0

Membaca dan menguji docstring

Di terminal pada folder geometri.py, jalankan:

python -m pydoc geometri.luas_persegi
python -m doctest -v geometri.py
python -m pydoc -w geometri

Perintah pertama menampilkan bantuan, kedua memeriksa tiga contoh masukan dan hasil, dan ketiga membuat geometri.html. Dalam sesi Python interaktif, kamu juga dapat menjalankan import geometri lalu help(geometri.luas_persegi) atau membaca atribut __doc__.

Alat dokumentasi dapat mengimpor modul. Karena itu, letakkan demonstrasi dalam penjaga __main__ dan gunakan sumber proyek yang kamu pahami. Doctest membantu mendeteksi contoh kedaluwarsa, tetapi tidak menggantikan seluruh pengujian fungsi.

Memilih pdoc atau Sphinx

pdoc dan pdoc3 merupakan proyek yang berbeda; pdoc3 bukan nama versi terbaru pdoc. Contoh di sini memakai paket pdoc.

Setelah membuat dan mengaktifkan venv mengikuti Bab 18, jalankan:

python -m pip install pdoc
python -m pdoc geometri.py -o docs-pdoc

Buka docs-pdoc/geometri.html. Untuk dokumen yang menggabungkan tutorial, panduan penggunaan, dan API, kamu dapat memakai Sphinx.

Paket sumber contoh menyediakan docs/conf.py berikut:

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
project = "Geometri"
extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
html_theme = "alabaster"

File docs/index.rst berisi:

Dokumentasi Geometri
====================

.. automodule:: geometri
   :members:

Dari folder proyek, jalankan:

python -m pip install sphinx
python -m sphinx -b html docs docs-html

Buka docs-html/index.html. Jalur pada conf.py menunjuk folder induk docs, tempat geometri.py berada. Ekstensi autodoc membaca docstring; napoleon membantu mengolah gaya Google atau NumPy. Sphinx Quickstart dapat digunakan untuk proyek yang lebih besar; periksa struktur folder yang dipilih sebelum menyesuaikan jalur import.

Menjaga dokumentasi tetap akurat

Untuk modul, jelaskan tujuan dan isi utamanya. Untuk kelas, jelaskan atribut serta metode publik setelah kamu mempelajari OOP. Pilih satu gaya docstring dalam proyek. Rincian implementasi hanya perlu dicantumkan jika mempengaruhi cara memakai fungsi.

Praktik Mandiri

L01-P01 – Dokumentasikan keliling

Buat fungsi keliling_persegi() untuk masukan angka berhingga yang nonnegatif. Jelaskan parameter, hasil, dan error; tambahkan dua doctest.

Kriteria selesai: Masukan 3 menghasilkan 12; masukan 0 menghasilkan 0. Input negatif ditolak. Doctest lulus.

import math


def keliling_persegi(sisi):
    """Hitung keliling sisi int atau float yang nonnegatif.

    >>> keliling_persegi(3)
    12
    >>> keliling_persegi(0)
    0
    """
    if type(sisi) not in (int, float):
        raise TypeError("Sisi harus int atau float.")
    if sisi < 0 or (
        isinstance(sisi, float) and not math.isfinite(sisi)
    ):
        raise ValueError("Sisi harus berhingga dan nonnegatif.")
    return 4 * sisi


print(keliling_persegi(3))
print(keliling_persegi(0))

Rangkuman

Docstring menjelaskan perilaku yang benar-benar diterapkan. help() dan pydoc menampilkan dokumentasi; doctest memeriksa contoh interaktif. pdoc dan Sphinx membantu menghasilkan HTML ketika dokumentasi bertambah.

Referensi dan Materi Pendamping

• PEP 257: konvensi docstring
• pydoc: dokumentasi dan bantuan
• doctest: menguji contoh interaktif
• Dokumentasi pdoc
• Sphinx: memulai dokumentasi
• Pendamping Bab 17: modul dan paket

Edisi September 2026. Contoh dan nomor praktik sesuai dengan buku.

FAQ | Lampiran 1 | Lampiran 2 | Lampiran 3 | Lampiran 4 | Lampiran 5 | Lampiran 6 | Lampiran 7