Skip to content

docs: teach the tour and the runbooks about flask - #24

Open
ttncode wants to merge 1 commit into
mainfrom
docs/flask-in-the-living-docs
Open

ttncode wants to merge 1 commit into
mainfrom
docs/flask-in-the-living-docs

Conversation

@ttncode

@ttncode ttncode commented Sep 14, 2026

Copy link
Copy Markdown
Owner

What this changes

flask reached README.md and docs/PROVENANCE.md when it landed, but not
docs/tour/ or docs/runbook/. Those were not stale in the obvious way — the
tour says outright to run scaffold list rather than trust a list written into
it, and nothing anywhere claims a count of adapters. They were narrow: four
sentences describe a rule that flask is the first adapter to answer
differently, and a reader following them would look in the wrong file.

  • docs/tour/08-adapters.md said an adapter runs "a framework's own
    generator". Flask ships none, so the package manager's project init stands in
    (uv init --bare, which writes a pyproject.toml and nothing else) and the
    overlay supplies the application. That is a fact about the mechanism, not
    about one adapter: it is what shows the overlay does not depend on a
    framework generator existing.
  • docs/tour/01-toolchain.md is the page about where a version is pinned,
    and had two answers. Flask is a third: mise.toml pins uv and no python,
    because uv resolves its own managed interpreter and would install a
    mise-pinned one only to ignore it.
  • docs/runbook/bump-a-toolchain-version.md listed where to look for a
    version. Searching the [tools] blocks for flask's python finds nothing, so
    the bullet now names .python-version and the --python argument in
    adapters/flask/adapter.env that sets requires-python at generation.
  • docs/runbook/add-an-adapter.md told an author to reach for
    ADAPTER_POST_GENERATE "only once you've hit a real generator bug". That
    stays true for a framework generator, but where the generator writes only a
    manifest the dependencies are ordinary setup, and adapters/flask uses the
    field for exactly that. Its mise.toml section and its adapter.env sample
    gain the same one-clause correction.

No prose was rewritten, no section added, and no example replaced — each edit
extends a sentence that had become narrower than the code.

How it was verified

  • bats tests/documentation.bats — 4/4
  • mise run lint
  • Every claim checked against the file it describes rather than from memory:
    adapters/flask/mise.toml pins uv and no python, .python-version reads
    3.13, and adapters/flask/adapter.env's generator carries --python 3.13.
  • No line over 80 columns, matching the surrounding documents.

Checklist

  • mise run lint passes
  • mise run test-runner passes
  • New behaviour has a test that fails without the change — n/a: no
    behaviour changes, this is documentation only
  • Docs that describe changed behaviour were updated in the same commit
  • No unrelated changes

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.

1 participant