Repository navigation
nvx-rs: keep the README's module table to one short line per module - #968
Merged
Pedro Henrique Penna (ppenna) merged 3 commits intoOct 28, 2026
Merged
Conversation
The module table under the README's Layout held each module's whole description in one Markdown line. Its 45 rows took about 55,000 characters: 42 were longer than 200, 14 longer than 1,000, and those of nvx::host::template and nvx::guest::clone longer than 7,000. Rendered, a reader scrolled through screens of one cell to reach the next module, and in review a change to a description replaced its whole line, which hid the change itself. Each row now says in one line what its module is for, in at most 200 characters, and links to the module's section, a heading with the module's path, after the table. The section holds the description that the row held, word for word, wrapped at 80 columns like the rest of the README, with a paragraph for each type or operation, so that a change to a description touches only the lines that it changes. The rows of nvx::Hypervisor, nvx::host::cli, and nvx::guest, which were already that short, keep their text, which their sections repeat. The table's second column, which now gives each module's purpose rather than its contents, is called Purpose. The descriptions' links resolve from their sections as they did from the table, and links into the README, such as #distro-bindings and #checked-handoff, keep their targets. Part of #964. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The README of nvx-rs now gives each module a row that says what it is for and a section after the module table that holds its details. Without a rule, the rows would grow again, as they did when open pull requests extended them with each type or operation that a module gained. The README says above the table that a module's details go in its section, and that its row, at most 200 characters long, changes only when the module's purpose does. .github/copilot-instructions.md gives the same rule in a new Documentation section, so that an agent that changes a module puts the module's new details in its section, wrapped like the rest of the README. Part of #964. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The README of nvx-rs says above its module table that each row says in one line, of at most 200 characters, what a module is for, and links to the module's section after the table, which holds the module's details. Nothing kept the rows from growing again as modules gain types and operations, which is how they had grown to thousands of characters. A test in scripts/test_nvx_tools.py reads the table and fails for a row that is longer than 200 characters, that does not link its module to a section, or that links it to an anchor other than the one that GitHub gives the module's heading, as the Markdown link check computes it, or to a heading that does not follow the table. It runs in the NVX CLI jobs with the rest of the module, documentation-only changes included. Part of #964. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are reported for the README module-documentation reorganization.
No open issues 🎉
What changed in this PR
Reorganizes the nvx-rs README’s module documentation to make the Layout table easier to scan and future documentation changes easier to review, addressing #964.
Changes:
- Replaces lengthy table descriptions with short, linked summaries and moves the existing details into 45 module sections.
- Documents the 200-character row limit and where module details belong.
- Adds a regression test for row length, module links, and section placement.
| File | Description |
|---|---|
scripts/test_nvx_tools.py |
Adds checks for short module rows linking to matching sections after the table. |
nvx-rs/README.md |
Separates concise module summaries from detailed, wrapped descriptions. |
.github/copilot-instructions.md |
Records the module-table documentation convention. |
Review effort: Balanced
Pedro Henrique Penna (ppenna)
deleted the
agents/issue-964-readme-module-table
branch
October 28, 2026 21:33
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.
Closes #964
The module table under Layout in
nvx-rs/README.mdhad stopped being an overview: each of its 45 rows held its module's whole description on one Markdown line, about 55,000 characters in all, with rows of up to 8,472 characters. Rendered, a reader scrolled through screens of one cell to reach the next module, and in review any change to a description replaced its whole line.Changes
### <module>section after the table. Each section holds the row's former description word for word, wrapped at 80 columns like the rest of the README, with a paragraph per type or operation, so that a change touches only the lines that it changes. The second column is now Purpose rather than Contents. The rows ofnvx::Hypervisor,nvx::host::cliandnvx::guest, which already had this form, keep their text. The two notes after the table, on GPT lower layers and lowering functions, stay where they were, before the new sections..github/copilot-instructions.md: a module's details go in its section, and its row changes only when the module's purpose does.scripts/test_nvx_tools.pyfails for a row longer than 200 characters, a row that does not link its module to a section, or one that links to another heading's anchor or to a heading that does not follow the table.Sequencing
#888 merged while this branch was in progress; the branch is rebased onto it, and its README additions (
ClonePlan::newandCheckedDistro::geometry) are in the sections ofnvx::host::templateandnvx::host::sandbox. The other open pull requests that edit rows of the table conflict with this change innvx-rs/README.md; whichever lands second moves its README text into the module's section.Validation
dev(e2f6af5) with its new section: all 45 match word for word, with only a final period added.python scripts/check_markdown_links.pypasses. It resolves each row's anchor: breaking one made it fail.python -m unittest scripts/test_nvx_tools.py scripts/test_markdown_links.pypasses on Windows (600 tests, 35 skipped). The new test fails, as it should, for a 251-character row and for a row linked to another module's section.scripts/test_module_diagrams.pyandscripts/test_crate_release.pypassed before the rebase onto nvx-rs: plan the clones of templates, and check their block geometry #888, which changed none of their inputs.cargo test --locked --lib the_readme_documents_every_code_with_its_kind, the nvx-rs test that reads the README, passes.