Skip to content

docs: generate server options as list-table for stable diffs - #4426

Open
stevenvegt wants to merge 2 commits into
masterfrom
docs/list-table-server-options
Open

docs: generate server options as list-table for stable diffs#4426
stevenvegt wants to merge 2 commits into
masterfrom
docs/list-table-server-options

Conversation

@stevenvegt

Copy link
Copy Markdown
Member

What

Changes the server options documentation generator to emit a list-table directive instead of an RST simple table, and adds a docs-docker Makefile target.

Why

The simple-table format pads every cell to the widest value in its column. Adding one option whose key, default, or description becomes the new column maximum reformats every row in the file. In #4420, adding 2 options produced a 142-line diff in server_options.rst because the new description was 9 characters longer than the previous longest, adding 9 trailing spaces to all 70 rows.

A list-table has no cross-row alignment: each row is its own 3-line block, so adding an option is always a 3-line diff, regardless of value lengths.

How

  • docs/rst_table.go: printRstTable emits * - key / - default / - description blocks. Empty cells become a bare - (no trailing whitespace anywhere in the output).
  • docs/generate_docs.go: directive changed to .. list-table:: with :header-rows: 1, keeping the existing :widths: 20 30 50 and :class: options-table. Also removes a stray debug println that wrote to stderr on every generation run.
  • docs/generate_docs_test.go: new test pinning the output format, including bold engine rows, \:8080 escaping, and empty cells.
  • server_options.rst and server_options_didnuts.rst regenerated (one-time full rewrite).
  • New make docs-docker target: builds the docs with the existing (previously unreferenced) docs/Dockerfile, so no Python/Sphinx tooling is needed on the host.

Rendering is unchanged

Verified by running the containerized Sphinx build against both the old and the new RST and diffing the output: the rendered tables in configuration.html are byte-identical (both directives produce the same docutils table node, with the same caption, column widths, and CSS class). The build shows the same 4 pre-existing warnings in both runs, none related to these files.

The simple-table format pads every cell to the widest value in its
column, so a single new option with a long description rewrites the
entire table (as happened in #4420, where 2 new options produced a
142-line diff). A list-table has no cross-row alignment: adding an
option is always a 3-line diff. The rendered HTML is identical,
verified by diffing Sphinx output of both formats.

Also removes a stray debug println from the generator.

Assisted-by: AI
The docs/Dockerfile existed but nothing referenced it. The new target
builds the documentation without requiring Python/Sphinx on the host.

Assisted-by: AI
@qltysh

qltysh Bot commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Qlty


Coverage Impact

⬆️ Merging this pull request will increase total coverage on master by 0.2%.

Modified Files with Diff Coverage (2)

RatingFile% DiffUncovered Line #s
Coverage rating: F Coverage rating: A
docs/rst_table.go100.0%
Coverage rating: F Coverage rating: F
docs/generate_docs.go0.0%250-253
Total82.4%
🤖 Increase coverage with AI coding...
In the `docs/list-table-server-options` branch, add test coverage for this new code:

- `docs/generate_docs.go` -- Line 250-253

🚦 See full report on Qlty Cloud »

🛟 Help
  • Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

  • Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

  • File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

    • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

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