[jaykv]

Stack 6 of 6 (more to follow). Base: feat/blueprints. Merge in order; each PR shows only its own changes.

Integration notes: the AI section now lives in docs/ai.md, blueprints and callbacks have their nav entries, the generated reference pages were regenerated from the merged code, and known-issues.md and several guides were corrected where the fixes PR changed behaviour. The branch is named docs-overhaul because a docs branch already exists. Verified at this tip: ruff, mypy --strict, 481 tests on Python 3.11 and 3.15, make docs-check and mkdocs build --strict.

Summary

Replaces the four-page docs site with a structured mkdocs-material site whose examples are run, not just written. mkdocs build --strict passes with zero warnings, and make docs-check loads, compiles and tests every manifest the guides show.

Based on chore/python-3.11-3.15. No library behaviour changes; the only edit under cliffy/ is one line of the cli dev docstring.

What changed

Site structure (docs/, mkdocs.yaml)

• Home: what cliffy is, a 60-second example, how it works.
• Get started: Installation (pip, uv, uvx, pipx / uv tool, extras, Python 3.11-3.15) and a Quickstart that builds a notes CLI in nine steps.
• Guides (13): manifest basics, params and types, commands/groups/aliases, command templates and global params, includes and merging, vars and Jinja, shell commands, Click and Typer backends, testing manifests, hot-reload dev loop, building executables, generating docs, editor setup.
• Reference (generated): CLI reference, manifest reference, examples gallery.
• Project: changelog (reconstructed from tags, with a 0.7.0 entry), contributing, migration notes, known issues.
• mkdocs.yaml: explicit nav, site_url, edit links, navigation tabs/sections/footer, strict: true with link and anchor validation. The git-committers plugin now runs only when CI is set, so local builds no longer call the GitHub API.
• Commented nav slots are left for blueprints.md and ai.md. Neither file is created here, so the owning MRs add them without a conflict.
• Removed docs/features.md, docs/getting-started.md, docs/schema.md.

Docs that run (docs/snippets/, scripts/docs.py, Makefile)

• Guides embed manifests from docs/snippets/ (11 files, 69 test cases) with pymdownx.snippets instead of copying YAML.
• scripts/docs.py generate writes docs/reference/cli.md from the click command tree, manifest.md from the pydantic models and examples.md from examples/*.yaml. It stops with a message when a new command, argument, model field or example has no description.
• scripts/docs.py check fails if those pages are stale, if a snippet include points at a missing file, if the README example drifts from the tested snippet, or if a snippet manifest fails to load, compile or pass its tests.
• New Makefile targets: docs-generate, docs-check, docs-build.

Other

• README.md trimmed from 280 lines to an overview that links into the site.
• .github/workflows/docs.yaml: also triggers on examples/*.yaml, which the gallery embeds at build time.
• cliffy/cli.py: the cli dev help example named a hello command that examples/hello.yaml does not have; it now uses python.

Things the old docs got wrong

Found by running every claim against the base branch:

• cli init mycli then cli load mycli.yaml (the old Getting Started) produces a CLI that fails to import.
• Inline name: str = typer.Option(...) params lose the typer.Option(...) part. The old home page, features page and README all used this form.
• The global_params example used a command without params, which raises NameError.
• The README demo GIF shows a prompt that examples/todo.yaml no longer produces.
• Broken links (features#ai-features, examples/), a Python 3.10 docs link, unprefixed AI model names, and the removed [dev] extra.

The new pages recommend the forms that work. The bugs themselves are listed in docs/project/known-issues.md and under Unresolved.

Breaking changes

1. Old page URLs are gone: /features/, /getting-started/ and /schema/ now 404. No redirects were added, because that needs a new docs dependency in pyproject.toml / uv.lock.
2. strict: true applies to the deploy workflow too. A broken link, or a git-committers API error, now fails mkdocs gh-deploy.
3. Nothing changes for library users.

Deviations from the brief

• repo_url stays https://github.com/jaykv/cliffy, not cliffy-sh/cliffy. github.com/cliffy-sh/cliffy returns a 301 to jaykv/cliffy, the API answers "Moved Permanently", and cliffy-sh.github.io/cliffy is a 404 while jaykv.github.io/cliffy serves the site. This matches pyproject.toml on the base branch. To flip it, change repo_url, repo_name, site_url and the git-committers repository in mkdocs.yaml, plus the links in README.md and scripts/docs.py.
• Branch is docs-overhaul, not docs/overhaul: a branch named docs already exists, so git cannot create docs/overhaul.
• No docs/ai.md stub. AI usage that is true on the base branch is in Installation and in the generated CLI reference.

How verified

Run locally on macOS arm64 with uv 0.13.0, one environment per Python, synced with uv sync --locked --all-extras --group docs:

Python	ruff format --check	ruff check	mypy cliffy --strict	mypy tests	pytest	docs check	mkdocs build --strict
3.11.11	pass	pass	pass	pass	188 passed	pass	pass, 0 warnings
3.15.0	pass	pass	pass	pass	188 passed	pass	pass, 0 warnings

• scripts/docs.py is also ruff- and mypy-clean, although the Makefile lint target does not cover scripts/.
• mkdocs build --strict prints only the Material team's MkDocs 2.0 notice and INFO lines, then Documentation built in 0.70 seconds, exit 0.
• Every "try it" command in the examples gallery was run. Console output in the pages was copied from real runs.
• cli load / update / list / info / remove, cli dev (including recovery from a broken manifest), cli build (manifest and loaded CLI, --python), cli docs (md/rst/html), uv tool install and uvx were exercised by hand on 3.13.
• Not checked: the rendered pages in a browser, and the docs workflow on GitHub.

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @jaykv, your pull request is larger than the review limit of 150,000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 243791c7-cfe6-41e6-9623-d204f9c1b547

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}