feat(docs): introduce MkDocs Material documentation site

[Kohei-Wada]

Summary

Implements #667: MkDocs + Material documentation site with auto-generated CLI/API references, deployed to GitHub Pages.

Site URL (after merge + Pages enablement): https://kohei-wada.github.io/taskdog/

Changes

• mkdocs.yml — Material theme with light/dark toggle, search, code copy; nav over the reorganized docs tree
• CLI reference (docs/reference/cli.md) — auto-generated from the Click command tree via mkdocs-click; adding a command updates the docs with no manual work
• API reference (docs/reference/api.md) — generated by scripts/generate_openapi_docs.py from create_app().openapi() without starting the server; build-time artifact, gitignored
• Docs reorganization (git mv, history preserved):
  • QUICKSTART.md → getting-started.md, CONFIGURATION.md → configuration.md, DESIGN_PHILOSOPHY.md → design-philosophy.md, OPTIMIZATION_ARCHITECTURE.md → optimization/architecture.md
  • Hand-written COMMANDS.md / API.md kept as reference/cli-guide.md / reference/api-guide.md (curated examples stay valuable next to the generated references)
  • contributing.md includes root CONTRIBUTING.md via pymdownx.snippets
• Removed manual Table of Contents sections (Material renders a sidebar TOC; the hand-written ones had drifted anchors)
• Fixed repo-relative links so they resolve both on GitHub and on the site
• Makefile: docs, docs-api, docs-serve, docs-build targets
• CI (.github/workflows/docs.yml): mkdocs build --strict on PRs touching docs/src, build + deploy to Pages on main push
• Docs deps as docs extra on the workspace root (uv run --extra docs), consistent with the uv workspace instead of a separate requirements.txt

Verification

• mkdocs build --strict: clean (0 warnings)
• Served locally and reviewed Home / CLI Reference / API Reference pages in a browser
• ruff check / ruff format on the new script: clean

Post-merge

• Enable GitHub Pages with build_type=workflow (Actions source), then the docs workflow deploys on push to main

Closes #667

[amazon-q-developer]

Summary

This PR introduces MkDocs Material documentation with auto-generated CLI/API references and GitHub Pages deployment. The implementation is well-structured and follows best practices for documentation generation.

Critical Issues Found

I've identified 3 critical issues that must be fixed before merge:

1. Missing workspace package installation - The workflow attempts to import taskdog_server without installing workspace packages first, causing the docs build to fail
2. Missing error handling - The OpenAPI generation script lacks error handling for app initialization failures
3. Missing Python version setup - The workflow doesn't explicitly set the Python version, risking inconsistent builds

All issues have actionable code suggestions attached to the relevant lines.

Overall Assessment

Once the critical issues are addressed, this implementation will provide excellent auto-generated documentation with minimal maintenance overhead. The use of build-time generation for API docs and mkdocs-click for CLI reference is a solid approach.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[amazon-q-developer]

🛑 Crash Risk: Missing error handling for app initialization. If create_app() fails due to missing configuration or environment variables, the script will crash without providing actionable debugging information. Add try-except block with descriptive error messages to handle potential failures during app creation or schema extraction.

Suggested change

	schema = create_app().openapi()
	def generate() -> str:
	try:
	schema = create_app().openapi()
	except Exception as e:
	raise RuntimeError(
	f"Failed to generate OpenAPI schema. Ensure the app can initialize "
	f"without external dependencies or set required environment variables. "
	f"Error: {e}"
	) from e
	sections: dict[str, list[str]] = {}
	for path, methods in schema["paths"].items():
	for method, operation in methods.items():
	tag = (operation.get("tags") or ["Other"])[0]
	sections.setdefault(tag, []).extend(
	_format_operation(path, method, operation)
	)
	lines = [HEADER]
	for tag in sorted(sections):
	lines.append(f"## {tag}")
	lines.append("")
	lines.extend(sections[tag])
	return "\n".join(lines).rstrip() + "\n"

[amazon-q-developer]

🛑 Logic Error: Missing package installation step. The script imports taskdog_server.api.app but the workflow doesn't install workspace packages before running the docs generation. Add uv sync or similar to install all workspace packages before the build step, or the import will fail at runtime.

Suggested change

	- name: Install uv
	uses: astral-sh/setup-uv@v7
	- name: Build docs
	run: |
	uv run --extra docs python scripts/generate_openapi_docs.py
	uv run --extra docs mkdocs build --strict
	- name: Install uv
	uses: astral-sh/setup-uv@v7
	- name: Install workspace packages
	run: uv sync --all-packages
	- name: Build docs
	run: |
	uv run --extra docs python scripts/generate_openapi_docs.py
	uv run --extra docs mkdocs build --strict

[amazon-q-developer]

Missing Python version setup in workflow. The workflow installs uv but doesn't specify which Python version to use. While uv may use a default Python, explicitly setting the Python version ensures consistency with the project's requires-python = ">=3.12" requirement. Add a Python setup step with version 3.12 or later.

Suggested change

	- uses: actions/checkout@v7
	- name: Install uv
	uses: astral-sh/setup-uv@v7
	- uses: actions/checkout@v7
	- name: Set up Python
	uses: actions/setup-python@v5
	with:
	python-version: '3.12'
	- name: Install uv
	uses: astral-sh/setup-uv@v7