feat(docs): migrate documentation to MkDocs with auto-generated API reference

[major]

Summary

• Migrate documentation from Jekyll to MkDocs with Material theme
• Add auto-generated API reference using mkdocstrings
• Add GitHub Actions workflow for deployment to GitHub Pages
• Consolidate and clean up Makefile documentation targets

Changes

Infrastructure

• Add docs dependency group to pyproject.toml with mkdocs-material, mkdocstrings, and plugins
• Create mkdocs.yml configuration with Material theme, navigation structure, and mkdocstrings setup

Content Migration

• Remove Jekyll configuration files (_config.yml, Gemfile, README.md)
• Update docs/index.md with relative links (removed Jekyll frontmatter and absolute URLs)
• Add full navigation structure to mkdocs.yml

API Reference Generation

• Add scripts/gen_api_ref.py to auto-generate API docs from Python docstrings
• Configure mkdocstrings with Google-style docstring parsing

CI/CD

• Add .github/workflows/docs.yaml for GitHub Pages deployment
• Workflow builds on PRs (validation) and deploys on pushes to main

Makefile Cleanup

• Remove duplicate generate-documentation target
• Rename doc to docs-readmes for clarity
• Keep docs-build and docs-serve for MkDocs operations

Usage

# Install docs dependencies
uv sync --group docs

# Build docs locally
make docs-build

# Serve docs with hot-reload
make docs-serve  # http://127.0.0.1:8000

Known Pre-existing Issues

These are not introduced by this PR but surfaced during migration:

• Broken links in rag_guide.md to non-existent example files
• Broken anchor links in deployment_guide.md
• Some docstrings don't perfectly follow Google-style format (griffe warnings)

These can be addressed in follow-up PRs.

Summary by CodeRabbit

• Chores
  • Documentation is now automatically built and deployed to GitHub Pages on main.
  • Migrated documentation infrastructure to MkDocs with a new site config and local markdown site structure.
  • Added local commands to build, serve, and regenerate docs for local development.
  • API reference pages are auto-generated from source to keep docs in sync; legacy Jekyll docs removed.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds MkDocs-based documentation (configuration, build/serve targets, API reference generator), removes legacy Jekyll site files, and adds a GitHub Actions workflow to build and deploy the MkDocs site to GitHub Pages.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow .github/workflows/docs.yaml	New CI workflow: triggers on pushes to main, PRs to main, and manual dispatch; sets Python 3.12; installs uv and docs deps; builds MkDocs site; uploads artifact on main push; deploys to GitHub Pages with required permissions and concurrency.
MkDocs Configuration mkdocs.yml	New mkdocs configuration: site metadata, repo info, docs dir, Material theme (red palette, dark/light), plugins (search, mkdocstrings, gen-files, literate-nav, section-index), Markdown extensions, and navigation structure.
Project Dependencies pyproject.toml	Added docs dependency group containing mkdocs-material, mkdocstrings[python], mkdocs-gen-files, mkdocs-literate-nav, and mkdocs-section-index.
Makefile Targets Makefile	Removed generate-documentation; added docs-build, docs-serve, and docs-readmes; updated docs/config.puml rule to move generated diagram (mv docs/classes.puml docs/config.puml).
API Reference Generation scripts/gen_api_ref.py	New script that scans src/ for Python modules, generates reference/ Markdown files with mkdocstrings ::: directives, builds navigation with mkdocs_gen_files.Nav, sets edit paths, and writes reference/SUMMARY.md.
Removed Jekyll Files docs/Gemfile, docs/_config.yml, docs/README.md	Deleted legacy Jekyll/GitHub Pages configuration and site content files.
Documentation Content Update docs/index.md	Migrated links from external/HTML URLs to local Markdown paths, updated logo to a local asset, standardized section names and local navigation links.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Dev as Developer
participant GH as GitHub
participant Runner as Actions Runner
participant Pages as GitHub Pages
Dev->>GH: push to main / open PR / manual dispatch
GH->>Runner: enqueue docs workflow (build job)
Runner->>Runner: checkout code, setup Python, install uv & deps
Runner->>Runner: run mkdocs build -> produce site/
Runner->>GH: upload site/ artifact (on push to main)
GH->>Runner: trigger deploy job (requires build)
Runner->>Pages: deploy site via actions/deploy-pages
Pages-->>GH: confirm deployment
GH-->>Dev: publish status / deployment URL

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• tisnik
• radofuchs

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: migrating documentation from Jekyll to MkDocs and adding auto-generated API reference support.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[major]

@CodeRabbit I'll send you a big bag of carrots in exchange for a helpful review of my draft PR.

[coderabbitai]

@major 🥕 That's an offer I can't refuse! I'll hop right on this documentation migration PR and give it a thorough review. Let me examine the Jekyll to MkDocs migration, the auto-generated API reference setup, the GitHub Actions workflow, and all the other changes you've made.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docs.yaml:
- Around line 13-21: The pull_request trigger's paths list is missing the
workflow file entry, so update the workflow YAML by adding the same workflow
file path currently included under the push trigger into the pull_request.paths
array; specifically edit the pull_request -> paths block to include the workflow
filename string (matching the entry under push) so PRs that modify the workflow
file will also trigger the docs workflow.

🧹 Nitpick comments (1)

scripts/gen_api_ref.py (1)

30-34: Consider adding options directive for consistency.

The generated markdown only contains the basic ::: module directive. Consider adding default options to ensure consistent rendering across all modules, especially if some modules have different characteristics.

Optional enhancement

     with mkdocs_gen_files.open(full_doc_path, "w") as fd:
         ident = ".".join(parts)
-        fd.write(f"::: {ident}\n")
+        fd.write(f"::: {ident}\n")
+        fd.write("    options:\n")
+        fd.write("      show_submodules: true\n")

This is optional since mkdocstrings inherits default options from mkdocs.yml.