Skip to content

docs: fix the last drifted claims, and make usage-line drift impossible - #1

Merged
FZ2000 merged 1 commit into
mainfrom
fix/remaining-doc-drift
Jul 31, 2026
Merged

docs: fix the last drifted claims, and make usage-line drift impossible#1
FZ2000 merged 1 commit into
mainfrom
fix/remaining-doc-drift

Conversation

@FZ2000

@FZ2000 FZ2000 commented Jul 31, 2026

Copy link
Copy Markdown
Owner

The audit's remaining findings, plus a structural fix so this class stops
recurring.

CONSOLE TRANSCRIPTS THE CODE CANNOT PRODUCE

docs/commands/README.md promises "Output shown in console blocks is
real output from the command, not an illustration." Three blocks were
not:

  • getting-started.md showed feed sync stopped: complete. sync.py
    rewrites a surviving "complete" to TIME_BUDGET_EXHAUSTED before the
    summary prints, precisely so a truncated run cannot look finished —
    so that string never reaches a terminal. Now feed exhausted.
  • troubleshooting.md showed a 503 as [error] HTTP 503 from <url>: Service Unavailable followed by re-run with -v for the full traceback. Both lines are wrong: _advice_for_http prints
    "DeviantArt is having trouble (HTTP 503 Service Unavailable)", and
    for a 5xx offer_traceback is False so the second line never
    appears at all — and where it does appear it says "re-run with -v to
    see the request that failed". Replaced with the real two lines,
    captured by stubbing a 503.
  • auth.md showed [error] refresh failed: HTTP 401 .... The string
    "refresh failed" does not exist anywhere in dacli/. The real message
    names the refresh token and tells you to run da auth.

USAGE LINES — and the reason they drifted unnoticed

Three were stale: da daily had gained --json, da search user had
gained --json, and da sync watched had gained a mutually exclusive
group, so argparse prints [--user USER | --via-feed] where the doc
still showed [--user USER] [--via-feed].

tools/check_doc_flags.py already walks the parser, but it only ever
compared the flag tables. The usage: line above each table — the part
a reader copies verbatim — was checked by nothing. It is now: every
usage: da ... block in docs/ is resolved to its subparser and compared
against format_usage(), whitespace-normalised and first line only,
since argparse wraps to terminal width. 31 usage lines now verified
alongside the 67 flag rows.

The check earned its place immediately: I had fixed two usage lines by
hand from the audit's list, and it found a third I had missed
(da search user). Negative control confirmed — reverting one drifted
line takes the count from 0 problems to 1.

Two bugs in my own addition, both caught before pushing: I inserted the
call after the loop that prints problems, so usage findings were
counted but never displayed; and the summary line still said
"flag-table problem(s)" for what are now documentation problems
generally.

ADR 0007 had drifted past its own refactor: "thirteen command handlers"
(that is the top-level subcommand count; there are 29 handlers) and "the
largest module is 848 lines" (sync.py is ~1,200, and it is the walk plus
its checkpointing — not usefully divisible, which is worth saying rather
than quoting a number that will drift again).

Verified: ruff, mypy, doc references, doc flags + usage lines, codespell
all clean; lychee 194 OK / 0 errors with fragments; 868 tests pass.

The audit's remaining findings, plus a structural fix so this class stops
recurring.

CONSOLE TRANSCRIPTS THE CODE CANNOT PRODUCE

docs/commands/README.md promises "Output shown in `console` blocks is
real output from the command, not an illustration." Three blocks were
not:

  - getting-started.md showed `feed sync stopped: complete`. sync.py
    rewrites a surviving "complete" to TIME_BUDGET_EXHAUSTED before the
    summary prints, precisely so a truncated run cannot look finished —
    so that string never reaches a terminal. Now `feed exhausted`.
  - troubleshooting.md showed a 503 as `[error] HTTP 503 from <url>:
    Service Unavailable` followed by `re-run with -v for the full
    traceback`. Both lines are wrong: `_advice_for_http` prints
    "DeviantArt is having trouble (HTTP 503 Service Unavailable)", and
    for a 5xx `offer_traceback` is False so the second line never
    appears at all — and where it does appear it says "re-run with -v to
    see the request that failed". Replaced with the real two lines,
    captured by stubbing a 503.
  - auth.md showed `[error] refresh failed: HTTP 401 ...`. The string
    "refresh failed" does not exist anywhere in dacli/. The real message
    names the refresh token and tells you to run `da auth`.

USAGE LINES — and the reason they drifted unnoticed

Three were stale: `da daily` had gained `--json`, `da search user` had
gained `--json`, and `da sync watched` had gained a mutually exclusive
group, so argparse prints `[--user USER | --via-feed]` where the doc
still showed `[--user USER] [--via-feed]`.

tools/check_doc_flags.py already walks the parser, but it only ever
compared the flag *tables*. The `usage:` line above each table — the part
a reader copies verbatim — was checked by nothing. It is now: every
`usage: da ...` block in docs/ is resolved to its subparser and compared
against `format_usage()`, whitespace-normalised and first line only,
since argparse wraps to terminal width. 31 usage lines now verified
alongside the 67 flag rows.

The check earned its place immediately: I had fixed two usage lines by
hand from the audit's list, and it found a third I had missed
(`da search user`). Negative control confirmed — reverting one drifted
line takes the count from 0 problems to 1.

Two bugs in my own addition, both caught before pushing: I inserted the
call after the loop that prints `problems`, so usage findings were
counted but never displayed; and the summary line still said
"flag-table problem(s)" for what are now documentation problems
generally.

ADR 0007 had drifted past its own refactor: "thirteen command handlers"
(that is the top-level subcommand count; there are 29 handlers) and "the
largest module is 848 lines" (sync.py is ~1,200, and it is the walk plus
its checkpointing — not usefully divisible, which is worth saying rather
than quoting a number that will drift again).

Verified: ruff, mypy, doc references, doc flags + usage lines, codespell
all clean; lychee 194 OK / 0 errors with fragments; 868 tests pass.
@FZ2000
FZ2000 merged commit a2c8cd4 into main Jul 31, 2026
22 checks passed
@FZ2000
FZ2000 deleted the fix/remaining-doc-drift branch July 31, 2026 01:20
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