feat(docs): add Sphinx + GitHub Pages deploy workflow

[konard]

Closes #8.

Summary

Adds the same Sphinx-based GitHub Pages deploy pattern used by the JS and Rust pipeline templates, so repositories bootstrapped from this template can publish API documentation to <org>.github.io/<repo>/ without designing the workflow from scratch. Deploy is gated on push to main (not release: published), which is the canonical fix from link-foundation/relative-meta-logic#170.

What changed

• .github/workflows/docs.yml — new workflow.
  • Builds Sphinx on every push, pull_request, and workflow_dispatch that touches docs/**, src/**, pyproject.toml, or the workflow itself.
  • Deploys to GitHub Pages only when github.event_name == 'push' && github.ref == 'refs/heads/main'. PRs and forks build but do not deploy, so docs breakage is caught pre-merge without leaking write permissions.
  • concurrency.cancel-in-progress is false on main (matches the JS template) so a deploy never gets cancelled half-way.
  • Uses sphinx-build -W --keep-going so warnings fail the build.
• docs/ — minimal Sphinx scaffold.
  • conf.py — Furo theme, sphinx.ext.autodoc + autosummary (recursive), napoleon (Google-style, matches CONTRIBUTING.md), myst_parser for Markdown, and intersphinx to CPython. Inserts src/ into sys.path so autodoc finds my_package without an install in some local setups.
  • index.md, api.md — landing page and autosummary-generated API reference.
  • requirements.txt — pinned floor versions; mirrored under [project.optional-dependencies] docs in pyproject.toml for pip install -e ".[docs]".
• pyproject.toml — new docs optional-dependency group.
• .gitignore — ignore _site/ and docs/_autosummary/ (the latter is regenerated on every build).
• README.md — new API Documentation section covering local preview and the one-time Settings → Pages → Source = GitHub Actions toggle (cannot be automated; explains the failure mode if skipped).
• CONTRIBUTING.md — note to build docs locally when changing public APIs/docstrings.
• changelog.d/ — scriv fragment for the release notes.

How this prevents the bug from #8

The Sphinx playground-style 404 in relative-meta-logic#163 happened because the deploy was gated on if: github.event_name == 'release', so pushing to main never published a site. This workflow ships the correct gate (push to main + workflow_dispatch) from day one.

Test plan

• pip install -e ".[docs]" && sphinx-build -W --keep-going -b html docs _site — builds cleanly, no warnings.
• ruff check ., ruff format --check ., mypy src, pytest tests/ -v — all pass.
• python -c "import yaml; yaml.safe_load(open('.github/workflows/docs.yml'))" — workflow YAML is valid.
• Merge to main and confirm Pages deploys to https://link-foundation.github.io/python-ai-driven-development-pipeline-template/ after the one-time Settings → Pages → Source = GitHub Actions toggle.

Notes for downstream users

After bootstrapping a new repository from this template, update in docs/conf.py:

• project, author
• the autosummary target in docs/api.md (currently my_package)

Then flip Settings → Pages → Source = GitHub Actions once. The next push to main publishes the docs.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $2.657466

📊 Context and tokens usage:

• 84.3K / 1M (8%) input tokens, 19.5K / 128K (15%) output tokens

Total: (5.4K new + 78.0K cache writes + 3.3M cache reads) input tokens, 19.5K output tokens, $2.657466 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.7 (claude-opus-4-7)

📎 Log file uploaded as Gist (1396KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🔄 Auto-restart triggered (iteration 1)

Reason: CI failures detected

Starting new session to address the issues.

---

Auto-restart-until-mergeable mode is active. This run will stop after 5 restart iterations.

[konard]

Working session summary

All checks now pass on PR #10. The Build Package failure was a transient actions/upload-artifact@v4 finalization error from GitHub Actions' artifact storage backend (returned HTML instead of JSON on finalize) — the build itself completed successfully (python -m build and twine check both passed). Re-running the failed job resolved it.

Final status on #10:

• Build Package — pass
• Build docs — pass
• Lint and Format Check — pass
• Test (Python 3.13) — pass
• Changelog Fragment Check — pass
• Detect Changes — pass
• Auto Release / Manual Release / Deploy to GitHub Pages — skipped (expected on PRs)

---

This summary was automatically extracted from the AI working session output.

[konard]

🔄 Auto-restart-until-mergeable Log (iteration 1)

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $0.672120

📊 Context and tokens usage:

• 64.5K / 1M (6%) input tokens, 3.1K / 128K (2%) output tokens

Total: (20 new + 58.0K cache writes + 463.8K cache reads) input tokens, 3.1K output tokens, $0.672120 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.7 (claude-opus-4-7)

📎 Log file uploaded as Gist (3809KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🎉 Auto-merged

This pull request has been automatically merged by hive-mind.

• All CI checks have passed

---

Auto-merged by hive-mind with --auto-merge flag