Dokumentasi

Dokumentasi yang tertinggal dari kode lebih menyesatkan daripada tidak ada dokumentasi, sehingga sebagian besar isinya sebaiknya hidup berdampingan dengan kodenya sendiri. Python menyediakan jalurnya melalui docstring, yaitu string yang diletakkan pada baris pertama fungsi, kelas, atau modul dan dapat dibaca alat lain secara otomatis. Topik ini membahas konvensi penulisan docstring menurut PEP 257, gaya penulisannya yang umum, serta dua generator dokumentasi yang paling banyak digunakan, yaitu Sphinx dan MkDocs. Setelah membacanya, dokumentasi referensi dapat dibangun langsung dari kode yang sudah beranotasi.

Docstring sebagai bahan mentah dokumentasi#

Docstring disimpan Python pada atribut __doc__ dari objek yang memilikinya, tanpa alat tambahan apa pun. Tempat ini menjadi bahan mentah bagi fungsi help(), pemeriksa statis, dan generator dokumentasi, sehingga penjelasan antarmuka yang ditulis sekali dapat muncul di banyak tempat. Contoh berikut menampilkan docstring sebuah fungsi melalui atribut tersebut, kemudian memanggil fungsinya.

def frekuensi_kata(teks):
    """Menghitung frekuensi kemunculan setiap kata pada teks.

    Kata dipisahkan oleh spasi, dan pencacahannya tidak
    peka huruf besar maupun huruf kecil.

    Argumen:
        teks: kalimat yang akan dianalisis.

    Mengembalikan:
        dictionary berisi pasangan kata dan frekuensinya.
    """
    hitungan = {}
    for kata in teks.lower().split():
        hitungan[kata] = hitungan.get(kata, 0) + 1
    return hitungan


print(frekuensi_kata.__doc__)
print(frekuensi_kata("apel Apel jeruk JERUK mangga"))

Menghitung frekuensi kemunculan setiap kata pada teks.

    Kata dipisahkan oleh spasi, dan pencacahannya tidak
    peka huruf besar maupun huruf kecil.

    Argumen:
        teks: kalimat yang akan dianalisis.

    Mengembalikan:
        dictionary berisi pasangan kata dan frekuensinya.

{'apel': 2, 'jeruk': 2, 'mangga': 1}

Keluaran tersebut menyalin docstring apa adanya, termasuk indentasi baris kelanjutannya, karena atribut __doc__ menyimpan teks dalam bentuk mentah. Fungsi help() membaca sumber yang sama lalu menampilkannya dalam bentuk yang lebih rapi, sehingga docstring yang baik otomatis memperbaiki bantuan interaktif di REPL.

Konvensi penulisan docstring#

PEP 257 menetapkan konvensi dasar penulisan docstring. Baris pertamanya adalah ringkasan satu kalimat yang diawali huruf kapital dan diakhiri titik, ditulis dalam bentuk kalimat perintah seperti “Menghitung” atau “Mengembalikan”. Apabila penjelasannya berlanjut, ringkasan dipisahkan satu baris kosong dari rincian berikutnya, sebagaimana terlihat pada fungsi frekuensi_kata di atas. Untuk penjelasan yang cukup satu baris, docstring ditutup pada baris yang sama.

def dua_kali(teks):
    """Mengembalikan teks yang diulang dua kali."""
    return teks + teks

Bagian rincian memiliki beberapa gaya penulisan yang dapat dibaca generator dokumentasi. Ketiganya menyampaikan hal yang sama, dan pilihan diputuskan sekali lalu dijaga konsisten di seluruh proyek.

Sphinx dan MkDocs#

Sphinx adalah generator dokumentasi yang menulis keluarannya dalam format reStructuredText dan menjadi alat yang membangun dokumentasi resmi Python itu sendiri. Ekstensi autodoc miliknya mengimpor modul proyek, lalu menarik docstring dari fungsi dan kelasnya menjadi halaman referensi API, sehingga referensi selalu mencerminkan kode terbaru. Konfigurasinya berada pada berkas conf.py berisi pengaturan Python biasa.

project = "Penghitung Kata"
author = "Penulis Contoh"
release = "0.1.0"
extensions = [
    "sphinx.ext.autodoc",
]
html_theme = "alabaster"

MkDocs menempuh jalur yang berbeda karena halamannya ditulis dalam Markdown, format yang sudah dipakai README dan berkas pendukung lainnya. Konfigurasinya berada pada berkas mkdocs.yml yang menyebutkan nama situs, tema, dan daftar navigasinya.

site_name: Penghitung Kata
theme:
  name: readthedocs
nav:
  - Beranda: index.md
  - Panduan: panduan.md
  - Referensi API: referensi.md

# tidak-dijalankan
# memasang mkdocs, menjalankan server lokal, lalu membangun situs statis
pip install mkdocs
mkdocs serve
mkdocs build

Kedua alat menghasilkan situs HTML statis yang dapat dihosting di mana saja, sebagaimana digambarkan diagram berikut. Sphinx unggul pada referensi API yang menarik docstring secara otomatis, sedangkan MkDocs unggul pada halaman panduan Markdown yang mudah ditulis. Banyak proyek memakai keduanya sekaligus, yaitu MkDocs untuk panduan dan halaman API yang ditarik melalui plugin seperti mkdocstrings.

Kesalahan umum#

Kesalahan pertama adalah docstring yang mengulang nama objeknya, misalnya “Fungsi frekuensi_kata menghitung frekuensi kata”. Kalimat semacam itu tidak menambah informasi karena namanya sudah terbaca di sampingnya. Docstring langsung menyatakan perilakunya, seperti “Menghitung frekuensi kemunculan setiap kata pada teks”.

Kesalahan kedua adalah menuliskan penjelasan antarmuka sebagai komentar # alih-alih docstring. Komentar tidak tersimpan pada atribut __doc__, sehingga help(), autodoc, dan alat dokumentasi lainnya tidak pernah melihatnya. Penjelasan yang ditujukan kepada pengguna objek ditempatkan di docstring, sedangkan komentar disisakan untuk catatan implementasi.

Kesalahan ketiga adalah membiarkan dokumentasi tertinggal setelah kode berubah. Situs yang dibangun sekali dan tidak pernah diperbarui menjelaskan versi lama yang sudah tidak ada. Pembangunan dokumentasi diperlakukan seperti pengujian, yaitu dijalankan ulang secara otomatis pada setiap perubahan sehingga situs yang tayang selalu berasal dari kode terbaru.

Ringkasan#

• Docstring disimpan pada atribut __doc__ dan menjadi sumber bagi help(), pemeriksa statis, serta generator dokumentasi.
• PEP 257 menetapkan ringkasan satu baris pada docstring, sedangkan rinciannya ditulis mengikuti gaya reStructuredText, Google, atau NumPy yang dijaga konsisten.
• Sphinx menarik docstring menjadi referensi API melalui autodoc, sedangkan MkDocs membangun situs dari halaman Markdown dengan konfigurasi mkdocs.yml.
• Keduanya menghasilkan situs HTML statis yang dibangun ulang bersama kode agar dokumentasi tidak tertinggal.

Referensi#

• PEP 257 – Docstring Conventions — Python Software Foundation — Konvensi resmi penulisan docstring pada Python.
• Sphinx documentation — Sphinx — Dokumentasi resmi Sphinx, termasuk ekstensi autodoc dan berkas conf.py.
• MkDocs — MkDocs — Panduan resmi MkDocs untuk berkas mkdocs.yml dan perintah build-nya.
• Example Google Style Python Docstrings — sphinxcontrib-napoleon — Contoh lengkap docstring bergaya Google yang dapat dibaca generator.