Dokumentasi dengan MkDocs

Sphinx berjaya karena autodoc, tetapi tidak semua proyek bersedia menulis reStructuredText. Banyak tim — terutama yang dokumennya sebagian besar berisi panduan, catatan rilis, dan wiki internal — sudah menulis segalanya dalam Markdown dan ingin format itu tetap dipakai. MkDocs lahir untuk kebutuhan tersebut: static site generator yang mengubah folder Markdown menjadi situs dokumentasi HTML, tanpa satu baris reST pun. Chapter ini membahas struktur konfigurasinya, tema Material yang menjadikannya populer, hingga cara mempublikasikan hasilnya.

Konsep Dasar MkDocs #

MkDocs membaca dua sumber: file konfigurasi mkdocs.yml di root proyek, dan folder docs/ berisi file Markdown. Seluruh isi docs/ menjadi halaman situs; urutan dan judulnya ditata di nav. Struktur minimal sebuah proyek:

proyek/
├── mkdocs.yml          # konfigurasi situs
└── docs/
    ├── index.md         # halaman depan
    ├── panduan.md       # halaman panduan
    └── api/
        ├── diskon.md    # halaman API diskon
        └── keranjang.md

Selama pengembangan, perintah mkdocs serve menjalankan server lokal yang otomatis memuat ulang halaman setiap file Markdown disimpan — perputaran edit dan pratinjau jadi nyaris instan.

Struktur mkdocs.yml #

Berikut contoh mkdocs.yml yang utuh untuk struktur folder di atas:

site_name: Toko Docs
site_description: Dokumentasi internal proyek toko.

theme:
  name: material

nav:
  - Beranda: index.md
  - Panduan: panduan.md
  - API:
      - Diskon: api/diskon.md
      - Keranjang: api/keranjang.md

Mari kita bedah tiap kuncinya:

1. site_name: judul yang tampil pada header situs dan tab browser.
2. theme: tema tampilan; material merujuk ke Material for MkDocs, dibahas setelah ini.
3. nav: daftar navigasi situs. Setiap entri berpasangan Judul: path-file. Entri bertingkat (misal API: dengan daftar di bawahnya) menjadi menu dropdown.

nav adalah bagian yang paling sering Anda sentuh. Tanpa nav, MkDocs menampilkan halaman menurut urutan alfabetis folder — memang otomatis, tetapi urutan belajar pembaca tidak mengikuti abjad. Menuliskan nav secara eksplisit membuat progression pembacaan jadi keputusan sadar: Beranda dulu, Panduan kemudian, barulah detail API.

Material for MkDocs #

Tema bawaan MkDocs tampilannya sederhana; itulah sebabnya sebagian besar proyek langsung beralih ke Material for MkDocs. Tema ini populer karena:

• pencarian teks instan yang bekerja tanpa server;
• mode gelap yang mengikuti preferensi browser;
• blok catatan, tab konten, dan diagram yang bisa ditulis langsung di Markdown;
• navigasi sisi kiri yang otomatis mengikuti heading tiap halaman.

Banyak fitur Material memakai sintaks Markdown extensi seperti !!! note untuk callout — bentuk yang lebih ramah daripada directive reST milik Sphinx.

Dokumentasi API dengan mkdocstrings #

MkDocs tidak bisa membaca docstring Python secara bawaan, tetapi plugin mkdocstrings menutup celah itu — perannya setara autodoc pada Sphinx. Plugin ini mengimpor kode Anda, membaca docstring (mengenali gaya Google melalui mkdocstrings[python]), lalu menyisipkannya ke halaman:

# API Diskon

::: toko.diskon

Baris ::: toko.diskon pada file api/diskon.md diganti render-nya dengan dokumen setiap member publik module toko.diskon. Hasilnya: pipeline Markdown-first, tetapi API reference tetap bersumber dari docstring yang hidup di dalam kode.

Deploy Hasil Build #

MkDocs menghasilkan situs statis di folder site/, sehingga bisa di-hosting di mana pun. Jalur paling populer adalah GitHub Pages, dan MkDocs membawa perintah khusus untuk itu:

$ mkdocs gh-deploy
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: site
INFO    -  Copying 'site' directory to 'gh-pages' branch
INFO    -  Your documentation should shortly be accessible at
          https://toko-tim.github.io/toko-docs/

Perintah mkdocs gh-deploy menjalankan build, lalu mendorong hasilnya ke branch gh-pages — branch yang GitHub Pages sajakan sebagai situs. Alternatif modernnya adalah GitHub Actions yang menjalankan mkdocs build pada setiap push; hasilnya sama, hanya pemicunya berpindah ke file workflow.

Kapan MkDocs, Kapan Sphinx #

Kedua tool menghasilkan output serupa, jadi pilihannya menyangkut selera tim dan bentuk dokumen:

Dengan dokumentasi terbangun, kita menggeser fokus ke kualitas kode itu sendiri. Chapter Type Hints untuk Maintainability membahas bagaimana anotasi tipe menjaga kode tetap aman saat terus berubah.