docs: add mkdocstrings setup with example API reference

CONTRIBUTING.md

@@ -1,8 +1,18 @@
 # Contributing
 
+## Docstrings
+
+This project uses [mkdocstrings] to generate API documentation from docstrings.
+Write docstrings in the [Numpydoc style].
+
+[mkdocstrings]: https://mkdocstrings.github.io/
+[Numpydoc style]: https://mkdocstrings.github.io/griffe/reference/docstrings/#numpydoc-style
+
 ## PR Title Convention
 
-This project uses [Conventional Commits](https://www.conventionalcommits.org/) for **PR titles**. Since we squash-merge, the PR title becomes the final commit message.
+This project uses [Conventional Commits] for **PR titles**. Since we squash-merge, the PR title becomes the final commit message.
+
+[Conventional Commits]: https://www.conventionalcommits.org/
 
 ### Format
 
@@ -12,19 +22,19 @@ type: description
 
 ### Allowed Types
 
-| Type | Purpose |
-|------|---------|
-| `feat` | A new feature |
-| `fix` | A bug fix |
-| `docs` | Documentation only |
-| `style` | Code style (formatting, semicolons, etc.) |
+| Type       | Purpose                                                 |
+| ---------- | ------------------------------------------------------- |
+| `feat`     | A new feature                                           |
+| `fix`      | A bug fix                                               |
+| `docs`     | Documentation only                                      |
+| `style`    | Code style (formatting, semicolons, etc.)               |
 | `refactor` | Code change that neither fixes a bug nor adds a feature |
-| `perf` | Performance improvement |
-| `test` | Adding or updating tests |
-| `build` | Build system or external dependencies |
-| `ci` | CI configuration |
-| `chore` | Other changes that don't modify src or test files |
-| `revert` | Reverts a previous commit |
+| `perf`     | Performance improvement                                 |
+| `test`     | Adding or updating tests                                |
+| `build`    | Build system or external dependencies                   |
+| `ci`       | CI configuration                                        |
+| `chore`    | Other changes that don't modify src or test files       |
+| `revert`   | Reverts a previous commit                               |
 
 ### Examples
 

docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: improved_octo_fortnight.math

pyproject.toml

@@ -19,4 +19,4 @@ tag_sign = false
 check_dirty = false
 
 [dependency-groups]
-docs = ["zensical"]
+docs = ["mkdocstrings-python", "zensical"]

src/improved_octo_fortnight/math.py

@@ -0,0 +1,64 @@
+"""Basic math operations."""
+
+
+def add(a, b):
+    """Add two numbers.
+
+    Parameters
+    ----------
+    a : int or float
+        The first number.
+    b : int or float
+        The second number.
+
+    Returns
+    -------
+    int or float
+        The sum of `a` and `b`.
+
+    Raises
+    ------
+    TypeError
+        If `a` or `b` is not a number.
+
+    Examples
+    --------
+    >>> add(1, 2)
+    3
+    """
+    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
+        raise TypeError("Both arguments must be numbers.")
+    return a + b
+
+
+def fibonacci(n):
+    """Generate the Fibonacci sequence.
+
+    Parameters
+    ----------
+    n : int
+        The number of terms to generate. Must be non-negative.
+
+    Returns
+    -------
+    list of int
+        The first `n` terms of the Fibonacci sequence.
+
+    Raises
+    ------
+    ValueError
+        If `n` is negative.
+
+    Examples
+    --------
+    >>> fibonacci(6)
+    [0, 1, 1, 2, 3, 5]
+    """
+    if n < 0:
+        raise ValueError("n must be non-negative.")
+    seq = []
+    a, b = 0, 1
+    for _ in range(n):
+        seq.append(a)
+        a, b = b, a + b
+    return seq

zensical.toml

@@ -7,6 +7,7 @@ copyright = "Copyright © 2026 Tai Sakuma"
 nav = [
   { "Get started" = "index.md" },
   { "Markdown in 5min" = "markdown.md" },
+  { "API Reference" = "api.md" },
 ]
 # extra_css = ["stylesheets/extra.css"]
 # extra_javascript = ["javascripts/extra.js"]
@@ -73,3 +74,17 @@ toggle.name = "Switch to system preference"
 # [[project.extra.social]]
 # icon = "fontawesome/brands/github"
 # link = "https://github.com/user/repo"
+
+[project.plugins.mkdocstrings.handlers.python]
+inventories = ["https://docs.python.org/3/objects.inv"]
+paths = ["src"]
+
+[project.plugins.mkdocstrings.handlers.python.options]
+docstring_style = "auto"
+inherited_members = true
+show_source = false
+
+[project.plugins.mkdocstrings.handlers.python.options.docstring_options]
+method = "heuristics"                                                                                                 
+style_order = ["numpy", "google", "sphinx"]  
+default = "numpy"