Who this guide is for

• Learners building projects others may read or use
• Developers who want maintainable APIs and smoother onboarding
• Teams aiming for consistent docs across code and project guides

What you’ll learn

• How to write useful docstrings for functions, classes, and modules
• Differences between Google, NumPy, and reStructuredText docstring styles
• How to generate docs with Sphinx and MkDocs
• How hosted docs workflows (for example Read the Docs) usually work
• How to keep documentation aligned with code changes

Why this topic matters

Good documentation reduces repeated questions, clarifies intent, and shortens onboarding time. In production projects, clear docs are often as valuable as code correctness because they keep teams aligned.

Documentation is most effective when it is practical and close to code. Small, accurate updates over time are better than one large outdated document.

Core concepts

Write docstrings for behavior, not obvious syntax

Good docstrings explain purpose, inputs, outputs, and failure cases.

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

Document edge cases and constraints where needed.

Choose a docstring style and stay consistent

Common styles:

• Google style (popular, readable)
• NumPy style (common in scientific stack)
• reStructuredText style (frequent in Sphinx-heavy docs)

Consistency matters more than style preference.

Project docs with Sphinx or MkDocs

• Sphinx: strong API docs generation and rich extensions
• MkDocs: simple markdown-first docs sites

Sphinx quick setup (HTML docs generation):

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

This generates HTML documentation output in docs/_build/html.

MkDocs quick setup:

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

This starts a local docs site for rapid iteration.

Read the Docs integration basics:

• Push repository with docs config (mkdocs.yml or Sphinx config) to Git provider
• Connect repository in Read the Docs dashboard
• Enable automatic builds on new commits
• Verify published docs URL after build succeeds

Step-by-step walkthrough

Step 1 — Add docstrings to key code paths

Prioritize public functions and classes first.

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)

Step 2 — Create a docs starter structure

At minimum, keep:

• README.md for quick start
• docs/ for guides and references
• Contribution notes for setup and checks

A clear structure scales better than one giant markdown file.

Step 3 — Automate docs checks in workflow

Add docs checks in CI where possible:

• Lint markdown
• Build docs site
• Fail pipeline on broken links (if configured)

Treat docs drift as a quality issue, not optional cleanup.

Practical examples

Example 1 — Before/after docstring quality

Before:

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

After:

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:

• Function behavior and failure mode are clear without reading implementation details.

Example 2 — Minimal MkDocs page structure

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

Expected result:

• Searchable docs site with clear navigation for new contributors.

Common mistakes and how to avoid them

• Writing docs once and never updating -> Update docs in the same PR as code changes.
• Documenting obvious details but skipping edge cases -> Focus on assumptions, constraints, and failure behavior.
• Mixing many docstring styles in one repository -> Pick one style guide and apply consistently.
• Keeping only external docs without inline context -> Combine high-level docs with code-adjacent docstrings.

Quick practice

• Add docstrings to three public functions using one consistent style.
• Create a docs/ folder with index.md and one topic page.
• Write one “How to run tests” section in your project README.

Key takeaways

• Documentation quality directly affects team speed and code usability.
• Accurate docstrings are foundational for maintainable APIs.
• Sphinx and MkDocs solve different documentation needs; choose based on workflow.
• Documentation should evolve with code, not after code.

Next step

Continue to Concurrency & Parallelism. In the next guide, you will learn when to use threads, processes, and asyncio in Python.