Skip to content

nvx-rs: keep the README's module table to one short line per module, and describe each module after it #964

Closed

Description

Summary

The module table in nvx-rs/README.md (| Module | Contents |, under Layout) is no longer an overview. Each of its 45 rows is one Markdown line that holds the module's whole description: 42 rows are longer than 200 characters, 14 are longer than 1,000, and the table holds about 49,700 characters, 38% of the README. The longest rows are nvx::host::template (7,130 characters), nvx::guest::root (3,969), nvx::host::sandbox (3,638), nvx::guest::clone (3,587) and nvx::activation (2,235).

Rendered, a reader scrolls through screens of one cell to reach the next module. In review, any change to a description replaces its whole line. #951 adds about 4,500 characters inside the nvx::host::template row, so its diff shows a line of 12,996 characters replaced by one of 17,503, and the change itself is hard to find. Open pull requests keep growing these rows: 16 of them edit the rows of nvx::host::template, nvx::guest::clone, nvx::host::sandbox or nvx::guest::mappings.

Proposal

  • Make each row of the table a short summary of what the module is for: one sentence of at most 200 characters, with a link to the module's section. The rows of nvx::Hypervisor, nvx::host::cli and nvx::guest already have this form.
  • Move each module's details into a section of its own after the table, for example ### nvx::host::template, as prose wrapped like the rest of the README, with a paragraph or a list item per type or operation, so that a change touches only the lines it changes. The move keeps the current wording; shortening the descriptions can follow separately.
  • Say above the table that a module's details go in its section, and that its row changes only when the module's purpose does. Add the same rule to .github/copilot-instructions.md.

A check that fails when a row of the module table grows past the limit would keep it short; it is optional. The README's other tables already keep their cells short and are out of scope.

Acceptance criteria

  • No row of the module table is longer than 200 characters, and each links to its module's section.
  • Every description that the table holds today is in a section after it, with its wording unchanged by the move.
  • Links into the README, such as #distro-bindings and #checked-handoff, still resolve, and the Markdown link check passes.

Sequencing

The open pull requests that edit rows of the table (#888, #925, #926, #939, #940, #941, #949, #950, #951, #955, #956, #957, #958, #959, #960 and #961) conflict with this change in nvx-rs/README.md. Whichever lands second moves its README text into the module's new section.

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions