Skip to content

docs: refresh stale documentation - #738

Merged
yeongseon merged 2 commits into
mainfrom
docs/refresh-stale-737
Oct 7, 2026
Merged

yeongseon merged 2 commits into
mainfrom
docs/refresh-stale-737

Conversation

@yeongseon

Copy link
Copy Markdown
Owner

Fixes #737

Per-item summary of the acceptance checklist:

  • docs/deployment.md:391-403 generate --app-path — confirmed against src/azure_functions_openapi/cli.py: there is no --app-path. Replaced both snippets with --app function_app:app. Executed both (JSON and YAML) against examples/report_jobs; the JSON run emits all three /api/reports* paths.
  • llms.txt / llms-full.txt version — nothing in the repo syncs this field, so bumping 0.27.0 to 0.29.0 would just re-stale next release. Replaced the hard-coded version with a pointer to PyPI.
  • docs/assets/screenshots.yml — labeled historical rather than faking a recapture: a manifest header documenting that all nine captures are from 0.21.2 (2026-08-15), plus status: historical on each entry. scripts/check_screenshots.py --strict still passes.
  • SUPPORT.md — "3.11 and above" is now 3.11-3.14 (>=3.11,<3.15), matching requires-python.
  • docs/development.md, docs/contributing.md — removed Black (ruff does formatting and linting); replaced the duplicated tool-version tables with a pointer to .pre-commit-config.yaml and pyproject.toml (the two pins disagreed with each other and with the docs); corrected both Makefile tables against the real targets; documented the enforced 95% gate (fail_under = 95) in place of the stale 85% target, including docs/testing.md; and corrected the review claim — branch protection has required_approving_review_count: 0, so the CI checks are the merge gate, not an approval.
  • docs/usage.md — dedented the "Non-standard HTTP methods (OpenAPI 3.2)" heading and its first paragraph so it renders as ### instead of a code block.
  • ecosystem links — azure-functions-{langgraph,validation,logging,doctor,scaffold} (no -python) only redirect rather than resolve directly; repointed to the canonical *-python repos in docs/architecture.md, docs/deployment.md, and DESIGN.md. The README tables were already correct. azure-functions-durable-graph-python and azure-functions-knowledge-python are marked retired upstream and are correctly absent.
  • CONTRIBUTING.md CISA link — confirmed 404; replaced with the GitHub advisory for CVE-2025-30066 (GHSA-mrrh-fwg8-r2c3, 200).
  • docs/installation.md — explained that 4-python3.12 is an example and listed the supported tags; verified 4-python3.11 through 4-python3.14 all exist in the MCR tag list.

docs/architecture.md was touched for ecosystem links only, leaving the decorator-order content for #736.

Verification

  • mkdocs build --strict — clean
  • scripts/check_screenshots.py --strict, scripts/lint_mermaid.py, tools/lint_hatch_matrix.py, tools/lint_release_workflows.py, tools/lint_workflow_pins.py — all pass
  • pytest — 1021 passed, 29 skipped
  • every changed external URL curled: all 2xx
  • no Python source changed, so ruff had nothing to check

Fixes the 2026-10 documentation freshness audit.

- deployment.md: `generate --app-path ./function_app.py` is not a real flag;
  replace with `--app function_app:app` (verified against cli.py and by
  running both snippets against examples/report_jobs).
- llms.txt / llms-full.txt: drop the hard-coded 0.27.0 and point at PyPI so
  the files stop drifting every release.
- docs/assets/screenshots.yml: label all nine captures as historical
  (0.21.2, 2026-08-15) rather than faking a recapture.
- SUPPORT.md: "3.11 and above" -> 3.11-3.14, matching requires-python.
- development.md / contributing.md / testing.md: remove Black (ruff does
  formatting), stop duplicating tool version pins, correct the Makefile
  target tables, state the real 95% coverage gate, and fix the merge-approval
  claim (branch protection requires 0 approvals; CI checks are the gate).
- usage.md: dedent the "Non-standard HTTP methods (OpenAPI 3.2)" heading so
  it renders as a heading instead of an indented code block.
- Ecosystem links: point at the canonical `*-python` repositories in
  architecture.md, deployment.md, and DESIGN.md.
- CONTRIBUTING.md: the CISA alert URL 404s; link the GitHub advisory for
  CVE-2025-30066 instead.
- installation.md: explain that `4-python3.12` is an example tag and list the
  supported `4-python3.11` .. `4-python3.14` images.
@yeongseon
yeongseon merged commit fdbeb12 into main Oct 7, 2026
27 checks passed
@yeongseon
yeongseon deleted the docs/refresh-stale-737 branch October 7, 2026 12:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: refresh stale documentation (2026-10 audit)

1 participant