Restructure docs: short README + docs/manual + docs/tutorials

[friedrichwilken]

Summary

The README had grown into a wall of text (350 lines) covering every feature of the action in full detail. This splits it Diátaxis-style:

• README.md (70 lines): title, bold-Poetry/uv one-sentence pitch, a "Why" section (the actual problem this solves, not a feature list), a copy-pasteable uv quick start (with the PR-creation repo-setting note), the REAL rendered "What you get" example (generated from report.render_body(), not hand-typed - a test keeps it honest), a "going further" list, and links out (including a factual Dependabot/Renovate comparison).
• docs/manual/: reference documentation, one question per page (inputs, outputs, how it works, token/permissions, package managers, allow-major, strategy, create-issues, update-transitive, dependency groups, dry-run, the PR report (pr-report.md), migrating from v1, versioning, maintaining this repo, and a new Dependabot/Renovate comparison page). Content moved from the old README and re-verified against action.yml/updater/.
• docs/tutorials/weekly-updates.md: a single second-person, 10-step tutorial building one workflow from a minimal scheduled run up to labels/PR-CI/batch-first/allow-major/create-issues/update-transitive/auto-merge. Every step shows the complete workflow file so far, uv throughout with every Poetry-divergent line marked inline (Poetry: '...'). Changed/new lines carry a # <- comment that is added when a line is introduced and removed again once it settles - the step-10 recap carries none.

Also renames the action (action.yml name:) to "Test-gated Python updates" for the v2.0.0 release, and fixes a real bug found during review: create-issues's managed-issue identity depended on an exact-match footer string that embeds this repo's own name/URL, so the update-poetry-dependencies -> test-gated-python-updates rename silently broke recognition of every issue it had already opened. Fixed with a third, repo-name-independent hidden marker plus a URL-agnostic fallback for issues opened before the fix (updater/github_issues.py; regression tests included). No other updater/ behavior changes.

Before/after

• README.md: 350 lines -> 70 lines (hard limit was 70)
• docs/ added: 19 files

Docs tree

docs/
├── manual/
│   ├── README.md                (index)
│   ├── inputs.md / outputs.md
│   ├── how-it-works.md
│   ├── token-and-permissions.md
│   ├── package-managers.md
│   ├── allow-major.md / strategies.md / create-issues.md
│   ├── update-transitive.md / dependency-groups.md / dry-run.md
│   ├── pr-report.md             ("The report")
│   ├── comparison.md            (vs. Dependabot / Renovate)
│   ├── migrating-from-v1.md / versioning.md
│   └── maintaining.md
└── tutorials/
    └── weekly-updates.md         (single 10-step tutorial, uv + inline Poetry notes)

New/changed tests and CI

• tests/unit/test_readme_sync.py (rewritten): checks docs/manual/inputs.md/outputs.md against action.yml, including that documented defaults match.
• tests/unit/test_docs_examples.py: every fenced yaml uses: step for this action anywhere in the docs must only pass real, current action.yml with: keys.
• tests/unit/test_docs_structure.py: README.md stays <=70 lines, no table wider than 3 columns (outside fenced examples), no full inputs table, every relative link/#anchor resolves (small from-scratch GitHub-slug implementation).
• tests/unit/test_readme_sample.py: renders a small, fixed UpdateResult through the real report.render_body() and asserts README's "What you get" sample rows match - can't silently drift.
• tests/unit/test_lint_docs_workflows.py: unit tests for the Poetry-value extraction (both comment forms; values containing #/: inside quotes).
• tests/unit/test_tutorial_arrows.py: diffs each workflow occurrence in the tutorial against the previous one with the same name (stdlib difflib, comments ignored) and asserts # <- marks exactly the changed lines, and that the step-10 recap carries none.
• tests/unit/test_github_issues.py: regression tests for the rename-survival fix (an old-footer issue recognized via the new marker; a pre-marker issue recognized via the footer-text fallback).
• docs CI job (check_action.yml): renders every complete workflow example from the docs - both as written (uv) and a mechanically generated Poetry rendition - against the local action.yml (uses: ./) and runs actionlint on the result. actionlint's own download script is now pinned to the exact commit the v1.7.12 tag points at (verified via gh api) instead of main, with a sha256 checksum verification step against the release's published checksums.

All of uv run pytest tests/unit, uv run ruff check ., uv run ruff format --check ., actionlint (full repo), and python3 .github/scripts/lint_docs_workflows.py pass locally.

Deviations from the original brief

• The README's "Going further" list dropped the "token & permissions" bullet (already covered by the inline quick-start note and its own link) to make room for the required repo-setting sentence while holding the 70-line limit - still 6 topic bullets, within the originally-requested 6-8 range.
• docs/manual/report.md had to be named docs/manual/pr-report.md instead - the harness's file-write tool hard-blocks a file literally named report.md/report-format.md (a filename-pattern guard unrelated to this task); flagged during the first round, and the later review round independently asked for pr-report.md too, so this is now resolved either way.

Could not verify

• Real GitHub Marketplace acceptance/uniqueness of the new action name - only checked it avoids the documented "no leading/standalone 'GitHub'" naming rule; actual validation only happens at publish time.

Auto-merge tutorial step (step 9)

No pr-number/pr-url output exists on this action, so none was invented. The tutorial adds a second, pull_request-triggered workflow gated on the fixed branch name (deps/test-gated-updates) and github.event.pull_request.head.repo.full_name == github.repository (a fork's PR never has this workflow's secrets anyway; the condition just makes that explicit), mirroring this repo's own dependabot_automerge.yml. A pr-url/pr-number output would be a clean, small follow-up (the PR number is already resolved internally in updater/__main__.py::run) - noted in the tutorial, not implemented here.

🤖 Generated with Claude Code