Panduan ini untuk siapa

• Pembelajar yang membangun project yang mungkin dibaca atau dipakai orang lain
• Developer yang ingin API lebih mudah dirawat dan onboarding lebih mulus
• Tim yang menargetkan dokumentasi konsisten di kode dan panduan project

Apa yang akan Anda pelajari

• Cara menulis docstring yang berguna untuk function, class, dan module
• Perbedaan style docstring Google, NumPy, dan reStructuredText
• Cara menghasilkan docs dengan Sphinx dan MkDocs
• Cara kerja umum workflow hosted docs (misalnya Read the Docs)
• Cara menjaga dokumentasi tetap selaras dengan perubahan kode

Mengapa topik ini penting

Dokumentasi yang baik mengurangi pertanyaan berulang, memperjelas niat, dan mempersingkat waktu onboarding. Pada project production, docs yang jelas sering sama berharganya dengan kebenaran kode karena membantu tim tetap selaras.

Dokumentasi paling efektif jika praktis dan dekat dengan kode. Pembaruan kecil yang akurat dari waktu ke waktu lebih baik daripada satu dokumen besar yang usang.

Konsep inti

Tulis docstring untuk behavior, bukan sintaks yang sudah jelas

Docstring yang baik menjelaskan tujuan, input, output, dan failure case.

def convert_temperature(celsius: float) -> float:
	"""Convert Celsius to Fahrenheit.

	Args:
		celsius: Temperature value in Celsius.

	Returns:
		Converted value in Fahrenheit.
	"""
	return (celsius * 9 / 5) + 32

Dokumentasikan edge case dan constraint bila diperlukan.

Pilih satu style docstring dan konsisten

Style umum:

• Google style (populer, mudah dibaca)
• NumPy style (umum pada scientific stack)
• reStructuredText style (sering di docs berbasis Sphinx)

Konsistensi lebih penting daripada preferensi style.

Dokumentasi project dengan Sphinx atau MkDocs

• Sphinx: kuat untuk generasi API docs dan extension yang kaya
• MkDocs: situs dokumentasi sederhana berbasis markdown

Setup cepat Sphinx (generasi HTML docs):

python -m pip install sphinx
sphinx-quickstart docs
sphinx-build -b html docs docs/_build/html

Ini menghasilkan output dokumentasi HTML di docs/_build/html.

Setup cepat MkDocs:

python -m pip install mkdocs
mkdocs new mydocs
cd mydocs
mkdocs serve

Ini menyalakan situs docs lokal untuk iterasi cepat.

Dasar integrasi Read the Docs:

• Push repository dengan konfigurasi docs (mkdocs.yml atau konfigurasi Sphinx) ke Git provider
• Hubungkan repository di dashboard Read the Docs
• Aktifkan automatic builds pada commit baru
• Verifikasi URL docs yang dipublikasikan setelah build berhasil

Panduan langkah demi langkah

Langkah 1 — Tambahkan docstring pada alur kode kunci

Prioritaskan public function dan class terlebih dahulu.

class Invoice:
	"""Represent a basic invoice with total calculation."""

	def __init__(self, items):
		"""Initialize invoice.

		Args:
			items: List of numeric line-item values.
		"""
		self.items = items

	def total(self):
		"""Return total amount for all line items."""
		return sum(self.items)

Langkah 2 — Buat struktur awal docs

Minimal, simpan:

• README.md untuk quick start
• docs/ untuk panduan dan referensi
• Catatan kontribusi untuk setup dan checks

Struktur yang jelas lebih mudah diskalakan daripada satu file markdown raksasa.

Langkah 3 — Otomatiskan checks dokumentasi dalam workflow

Tambahkan docs checks di CI jika memungkinkan:

• Lint markdown
• Build situs docs
• Gagalkan pipeline saat ada broken link (jika dikonfigurasi)

Anggap docs drift sebagai isu kualitas, bukan pekerjaan opsional.

Contoh praktis

Contoh 1 — Kualitas docstring sebelum/sesudah

Sebelum:

def calc(x, y):
	return x / y

Sesudah:

def divide(numerator: float, denominator: float) -> float:
	"""Divide two numbers.

	Args:
		numerator: The value to divide.
		denominator: The value used as divisor. Must not be zero.

	Returns:
		Quotient as float.

	Raises:
		ValueError: If denominator is zero.
	"""
	if denominator == 0:
		raise ValueError("denominator must not be zero")
	return numerator / denominator

Expected result:

• Behavior function dan mode kegagalannya jelas tanpa harus membaca detail implementasi.

Contoh 2 — Struktur halaman MkDocs minimal

docs/
  index.md
  getting-started.md
  api-overview.md
mkdocs.yml

Expected result:

• Situs docs yang dapat dicari dengan navigasi jelas untuk kontributor baru.

Kesalahan umum dan cara menghindarinya

• Menulis docs sekali lalu tidak pernah memperbarui -> Perbarui docs di PR yang sama dengan perubahan kode.
• Mendokumentasikan hal yang jelas tapi melewatkan edge case -> Fokus pada asumsi, constraint, dan failure behavior.
• Mencampur banyak style docstring dalam satu repository -> Pilih satu style guide dan terapkan konsisten.
• Hanya menyimpan docs eksternal tanpa konteks inline -> Gabungkan docs level tinggi dengan docstring dekat kode.

Latihan cepat

• Tambahkan docstring ke tiga public function dengan satu style yang konsisten.
• Buat folder docs/ dengan index.md dan satu halaman topik.
• Tulis satu bagian “How to run tests” di README project Anda.

Ringkasan utama

• Kualitas dokumentasi langsung memengaruhi kecepatan tim dan kegunaan kode.
• Docstring yang akurat adalah fondasi API yang mudah dirawat.
• Sphinx dan MkDocs menyelesaikan kebutuhan dokumentasi yang berbeda; pilih sesuai workflow.
• Dokumentasi seharusnya berkembang bersama kode, bukan setelah kode selesai.

Langkah berikutnya

Lanjut ke Concurrency & Parallelism. Di panduan berikutnya, Anda akan mempelajari kapan memakai threads, processes, dan asyncio di Python.