Generate README.md from split spec sources - #114
Merged
Conversation
maximmaxim345
force-pushed
the
feat/split-readme-source
branch
2 times, most recently
from
July 14, 2026 11:03
28d3478 to
c395fd2
Compare
maximmaxim345
force-pushed
the
feat/split-readme-source
branch
from
July 21, 2026 08:46
c395fd2 to
9c7ea2b
Compare
README.md is now a generated single-page artifact, authored as per-section and per-role source files that tools/build-readme.py concatenates, rewriting cross-file links to page anchors and failing on duplicate or dangling anchors. The two colliding "Multiple servers" headings are disambiguated (server-initiated / client-initiated) because the build rejects duplicate anchors. A pre-commit hook and CI check keep README.md in sync.
The concatenation order and the document head move out of the build script into template.md, the assembly root: it holds the title, definitions, and role versioning, then lists the files to append with `<!-- include: <path> -->` directives. preamble.md is absorbed into it. The generator now drops HTML comments from the page unless a `<!-- keep: ... -->` line marks the next comment to persist, which is how the generated-file banner reaches the top of README.md. The generated README.md is unchanged.
The pre-commit hook now renders README.md from the staged content of template.md and its includes rather than the working tree, so a partial commit gets a README.md matching exactly what it commits. A README.md that matches no generated rendering is still refused as a direct edit.
Comment stripping and the `<!-- keep: ... -->` marker applied only to template.md. They now apply to every included file too, so an authoring note in any source stays out of the generated README unless a keep marker precedes it. No source has comments today, so README.md is unchanged.
maximmaxim345
force-pushed
the
feat/split-readme-source
branch
from
July 21, 2026 11:39
9c7ea2b to
ea7dfce
Compare
kahrendt
requested changes
Jul 21, 2026
GitHub keeps underscores in heading anchors, but the slug builder dropped them, so a link to a heading like `f_peak` would not resolve on GitHub.
kahrendt
pushed a commit
that referenced
this pull request
Jul 21, 2026
Builds on #114. This one only moves sections around, no content changes: - The overview sequence diagram comes out of the "Suggested correction strategy" subsection and becomes its own "Protocol overview" section near the top. - "Playback Synchronization" moves down next to the player role's audio sections. Both are plain moves, so the `README.md` diff is just those two blocks changing place. #114 and this PR together produce the same `README.md` as the original combined change. Depends on #114.
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
2 participants
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.
The spec used to be one big
README.md. It's now split into per-section and per-role source files, andREADME.mdis generated from them bytools/build-readme.py.The generated
README.mdin this PR matches the old one except for two things the build forces: the generated-file banner at the top, and the two duplicate "Multiple servers" headings, renamed to "(server-initiated)" and "(client-initiated)" (with their two inbound links) so their anchors stop colliding. No sections move, so the diff against the oldREADME.mdis tiny. Reordering the page is left to a follow-up PR.template.mdis where the assembly lives: the document head, then<!-- include: <path> -->lines in page order. Links between files are written file-relative and turned into page anchors at build time, and the build fails on duplicate or dangling anchors. HTML comments are stripped from the output unless a<!-- keep: ... -->line precedes them, which is what keeps the banner. The pre-commit hook regeneratesREADME.mdfrom the staged files and blocks hand-edits to it. CI runs the same--check. Also addsCONTRIBUTING.md.