Dokumentasi dengan Sphinx

Docstring yang tertata rapi baru bisa dibaca lewat help() di terminal atau editor. Pengguna library Anda, bagaimanapun juga, butuh halaman dokumentasi yang bisa dijelajahi lewat browser: daftar module yang bisa diklik, pencarian teks, dan tautan silang antar class. Sphinx adalah tool yang paling lama dan paling banyak dipakai untuk membangun dokumentasi semacam itu di ekosistem Python — termasuk dokumentasi resmi Python sendiri. Kekuatannya: Sphinx menyedot isi docstring langsung dari kode, sehingga dokumentasi dan implementasi tinggal di satu tempat.

Apa Itu Sphinx #

Sphinx adalah documentation generator. Cara kerjanya tiga lapis:

1. Sumber dokumen ditulis dalam format reStructuredText (reST) — file .rst berisi teks plus penanda struktural.
2. Extension autodoc mengimpor kode Python Anda, membaca atribut __doc__ dari tiap module, class, dan function, lalu menyalinnya ke dalam dokumen.
3. Sphinx merakit semuanya menjadi HTML (atau PDF, ePub, manual page) di folder _build/.

Karena autodoc mengimpor kode sungguhan, dokumentasi API tidak pernah kehilangan sinkron dengan nama function yang sebenarnya — docstring diambil langsung dari definisi terbaru.

Menyiapkan Proyek Sphinx #

Sphinx menyediakan wizard bernama sphinx-quickstart untuk membuat kerangka proyek dokumentasi. Transkrip ilustratif sesi tersebut kurang lebih seperti berikut:

$ sphinx-quickstart docs
Welcome to the Sphinx 7.2.6 quickstart utility.

> Separate source and build directories? [y/n] y
> Project name: Toko Toolkit
> Author name: Tim Toko
> Project release []: 1.0.0

Creating file docs/source/conf.py.
Creating file docs/source/index.rst.
Creating file docs/Makefile.

Finished: an initial directory layout has been created.

Hasil akhirnya berupa struktur folder seperti ini:

proyek/
├── toko/               # kode Python Anda
│   └── diskon.py
└── docs/               # proyek Sphinx
    ├── Makefile
    └── source/
        ├── conf.py     # konfigurasi build
        └── index.rst   # halaman depan

Bagian Penting conf.py #

File conf.py adalah pusat kendali Sphinx. Empat baris extensions berikut yang paling menentukan hasil akhirnya:

project = "Toko Toolkit"
author = "Tim Toko"
version = "1.0"
release = "1.0.0"

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
]

html_theme = "furo"

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}

Mari kita bedah perannya satu per satu:

1. autodoc: menyedot docstring dari kode — jantung dari seluruh mekanisme.
2. napoleon: mengenali docstring gaya Google dan NumPy dari Chapter Menulis Docstring, lalu mengubahnya menjadi reST. Tanpa extension ini, docstring Google style dirender apa adanya.
3. intersphinx: menghubungkan dokumentasi Anda dengan dokumentasi proyek lain. Konfigurasi di atas membuat role reST :func: yang merujuk ke sum otomatis menjadi tautan ke halaman function sum() di docs.python.org.
4. viewcode: menambahkan tautan [source] pada tiap entri API sehingga pembaca bisa melihat implementasinya.
5. html_theme: menentukan tampilan. Tema bawaan alabaster cocok untuk memulai; tema furo dan sphinx-rtd-theme adalah pilihan populer untuk proyek modern.

Menyedot Docstring dengan autodoc #

Dokumentasi Sphinx terdiri dari dua lapis dengan pembaca berbeda. Lapis narrative docs menjelaskan cara memakai library — tutorial, panduan instalasi, how-to. Lapis API reference mendata setiap function dan class secara otomatis. Directive automodule menjembatani keduanya; tulis pada file source/api.rst:

Dokumentasi API
===============

.. automodule:: toko.diskon
   :members:

Baris .. automodule:: toko.diskon memerintahkan Sphinx mengimpor module toko.diskon; opsi :members: menyertakan semua member publiknya. Module toko/diskon.py berisi docstring gaya Google yang sudah kita uji di Chapter sebelumnya:

"""Kalkulator diskon untuk toko (contoh API module).

Semua nominal dalam rupiah.
"""

BATAS_DISKON = 500_000


def hitung_diskon(total_belanja: float) -> float:
    """Hitung besar diskon untuk satu transaksi.

    Diskon berlaku bertingkat: 10% untuk total di atas
    batas diskon, 0% untuk total di bawahnya.

    Args:
        total_belanja: nilai transaksi sebelum diskon.

    Returns:
        Besar potongan harga dalam rupiah.
    """
    if total_belanja > BATAS_DISKON:
        return total_belanja * 0.10
    return 0.0

Setelah build, halaman api.html menampilkan ringkasan, Args, dan Returns persis seperti yang ditulis — Napoleon yang menerjemahkannya. Perbandingan dua lapis dokumentasi:

Build dan Hasilnya #

Build dijalankan lewat Makefile dari dalam folder docs/:

$ make html
Running Sphinx v7.2.6
building [html]: targets for 4 source files
updating environment: [new config] 4 added, 0 changed, 0 removed
build succeeded.

The HTML pages are in _build/html.

Folder _build/html berisi situs statis — buka index.html di browser dan seluruh dokumentasi siap dijelajahi. Setiap kali kode berubah, jalankan ulang make html; autodoc menarik docstring terbaru.

Sphinx, MkDocs, dan Read the Docs #

Tiga nama ini sering tertukar karena muncul bersamaan di halaman dokumentasi library:

Sphinx dan MkDocs adalah pesaing satu sama sama — keduanya menghasilkan HTML, dari sumber berbeda. Read the Docs bukan pesaing keduanya: platform ini bisa membangun proyek Sphinx maupun MkDocs setiap kali Anda mendorong commit. Bagi library besar dengan API luas, kekuatan Sphinx ada pada autodoc dan ekosistem extension; bagi proyek yang dokumennya sebagian besar naratif, alternatif berbasis Markdown sering kali lebih nyaman — pokok bahasan Chapter Dokumentasi dengan MkDocs.