Automated Python API Documentation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Establish a zero-maintenance documentation system using MkDocs and mkdocstrings that automatically generates API reference from source code.

Architecture: - MkDocs + Material Theme: Modern UI for documentation. - mkdocstrings: Extracts documentation directly from Python code and docstrings. - mkdocs-gen-files: Automatically generates Markdown files for every module in toolkitx/. - mkdocs-literate-nav + mkdocs-section-index: Automates navigation sidebar generation.

Tech Stack: Python, uv, MkDocs, Material for MkDocs, mkdocstrings, mkdocs-gen-files.

Task 1: Setup Dependencies

Files: - Modify: pyproject.toml

[ ] Step 1: Add documentation dependencies to pyproject.toml

Add docs optional dependencies:

[project.optional-dependencies]
dev = [
    "pytest>=9.0.2",
    "pytest-dotenv>=0.5.2",
    "ruff>=0.9.0",
]
docs = [
    "mkdocs>=1.6.0",
    "mkdocs-material>=9.5.0",
    "mkdocstrings[python]>=0.25.0",
    "mkdocs-gen-files>=0.5.0",
    "mkdocs-literate-nav>=0.6.0",
    "mkdocs-section-index>=0.3.0",
]

[ ] Step 2: Update lockfile

Run: uv lock

[ ] Step 3: Commit

git add pyproject.toml uv.lock
git commit -m "chore: add documentation dependencies"

Task 2: Configure MkDocs

Files: - Create: mkdocs.yml - Create: docs/index.md

[ ] Step 1: Create mkdocs.yml

site_name: ToolkitX Documentation
site_url: https://github.com/ider-zh/toolkitx
repo_url: https://github.com/ider-zh/toolkitx
edit_uri: edit/main/docs/

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy

plugins:
  - search
  - gen-files:
      scripts:
        - scripts/gen_ref_pages.py
  - literate-nav:
      nav_file: SUMMARY.md
  - section-index
  - mkdocstrings:
      handlers:
        python:
          paths: [.]
          options:
            docstring_style: google
            show_source: true
            show_root_heading: true
            show_category_heading: true

markdown_extensions:
  - admonition
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

[ ] Step 2: Create docs/index.md

# Welcome to ToolkitX

ToolkitX is a personal Python toolkit for common tasks, focusing on resilience, text processing, and lab tools like translators.

## Modules

- **Task Utils**: Resilience decorators and persistent task queues.
- **Text Utils**: Smart text truncation and word-count based splitting.
- **Lab**: Experimental tools including Baidu and Tencent translators.

## Getting Started

Check the [API Reference](reference/toolkitx/index.md) for detailed documentation of all modules.

[ ] Step 3: Commit

git add mkdocs.yml docs/index.md
git commit -m "chore: configure mkdocs and create index page"

Task 3: Implement Automated API Reference Generation

Files: - Create: scripts/gen_ref_pages.py

[ ] Step 1: Create scripts/gen_ref_pages.py

"""Generate the code reference pages and navigation."""

from pathlib import Path
import mkdocs_gen_files

nav = mkdocs_gen_files.Nav()

root = Path(__file__).parent.parent
src = root / "toolkitx"

for path in sorted(src.rglob("*.py")):
    module_path = path.relative_to(root).with_suffix("")
    doc_path = path.relative_to(root).with_suffix(".md")
    full_doc_path = Path("reference", doc_path)

    parts = tuple(module_path.parts)

    if parts[-1] == "__init__":
        parts = parts[:-1]
        doc_path = doc_path.with_name("index.md")
        full_doc_path = full_doc_path.with_name("index.md")
    elif parts[-1] == "__main__":
        continue

    nav[parts] = doc_path.as_posix()

    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
        ident = ".".join(parts)
        fd.write(f"::: {ident}")

    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))

with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

[ ] Step 2: Commit

mkdir -p scripts
git add scripts/gen_ref_pages.py
git commit -m "feat: add automatic api reference generation script"

Task 4: Update Makefile and Verify

Files: - Modify: makefile

[ ] Step 1: Add documentation targets to makefile

docs-serve:
    uv run --extra docs mkdocs serve

docs-build:
    uv run --extra docs mkdocs build

[ ] Step 2: Verify local documentation server

Run: make docs-serve (and check if it starts successfully, manually stop it after check)

[ ] Step 3: Verify build

Run: make docs-build Expected: site/ directory created with HTML files.

[ ] Step 4: Commit

git add makefile
git commit -m "chore: add documentation targets to makefile"