Repository navigation
docs: turn the README into a landing page, and run help examples with --execute - #20
Merged
Merged
Conversation
This was referenced Oct 9, 2026
tee8z
previously approved these changes
Oct 9, 2026
thebrandonlucas
force-pushed
the
docs/help-examples-execute
branch
2 times, most recently
from
October 13, 2026 18:56
041a6a1 to
e1dbb7d
Compare
This was referenced Oct 13, 2026
This was referenced Oct 13, 2026
thebrandonlucas
force-pushed
the
docs/help-examples-execute
branch
from
October 19, 2026 13:16
e1dbb7d to
3ac7bad
Compare
thebrandonlucas
force-pushed
the
docs/help-examples-execute
branch
2 times, most recently
from
October 19, 2026 19:19
8857782 to
38915c6
Compare
tee8z
reviewed
Oct 19, 2026
tee8z
left a comment
Contributor
There was a problem hiding this comment.
looks good, just some minor suggestions/questions
This was referenced Oct 19, 2026
… --execute The payments receive and wallets create help examples left out --execute, so copying them only described the request and exited 6. Both now pass --execute. A unit test now parses every voltage line in the user docs' shell blocks and every Examples line in each command's long help through the real command tree. Placeholder IDs stand in for UUIDs. An example that is not a GET must pass --execute or --dry-run, so a documented change cannot silently stop at a description again. It covers every Markdown user doc and the development guide, in sh, bash, shell, and console fences at any indent. Arguments are split on whitespace, so a quoted argument with spaces is not supported. The README was a 240-line manual. It is now a 92-line landing page: the Voltage logo (light and dark variants from the brand guide), a one-line pitch, three reasons to use it, install, a quick start that ends in a payment, a scripting example with the key exit codes, and a table of docs. Everything else moves, mostly verbatim, into docs/ by kind: guides (install, login and profiles, payments, requests, checkout, scripting), reference (output, exit codes), and concepts (the safety model), with an index at docs/README.md. The note on docs/plans moves to AGENTS.md. A new test checks that each relative link and HTML image path reaches an existing file, and each anchor an existing heading outside code fences. The development guide's staging receive example now passes --execute.
thebrandonlucas
force-pushed
the
docs/help-examples-execute
branch
from
October 20, 2026 11:58
38915c6 to
761d86a
Compare
tee8z
approved these changes
Oct 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack: master ← #20 ← #22 ← #57 ← #24 ← #19 ← #26 ← #27 ← #28 ← #29 ← #30 ← #55. Rebased onto master (#53, #56) on 2026-10-19.
Summary
This PR has two parts. #21 (README landing page) was merged into this branch, so the title now covers both.
payments receiveandwallets createhelp examples now pass--execute. Before, copying them only described the request and exited 6.voltageexample through the real command tree: each shell block in the Markdown user docs and the development guide, and everyExamples:line in each command's long help. A non-GET example must pass--executeor--dry-run. Placeholder IDs (WALLET_ID,ORG_ID, …) stand in for UUIDs. Arguments split on whitespace, so a quoted argument that contains spaces is not supported.docs/guides,docs/reference, anddocs/concepts, with an index atdocs/README.md. The note ondocs/plansmoves toAGENTS.md.Changes after review
AGENTS.mdkeeps both "Before you request review" (docs(agents): require skill review and the CRAP report before review #56) and "Work plans".rust-toolchain.tomlapplies to builds from a clone, not tocargo install --git..mdfiles underdocs/, so an image or other asset cannot break it.Checks
On
761d86a:cargo fmt --check,cargo clippy --locked --all-targets -- -D warnings,cargo machete --with-metadata: pass.cargo test --locked: 90 unit and 61 integration tests pass.VOLTAGE_BLESS=1 cargo test --lockedleaves the tree clean.python3 scripts/check-coverage.py: pass.scripts/crap-report.sh): no function at or above 20. Highest isapi::wait_for_paymentat 19.66, unchanged from or lower than master (19.66).voltage-pr-reviewand thevoltage-backend-engineeringRust checklist, against the stack base. Findings are fixed in this commit.Not run: the staging and live tutorials, which need credentials.