docs: compile every documentation code block#326
Conversation
Replace all ~375 hand-typed [source,cpp] blocks across the 30 doc
pages with includes of compiled sources, mirroring Boost.Capy, so an
example that breaks can no longer render on the site.
- test/doc/snippets: one TU per page; fragments compile and run as
test suites, exercising loopback socket pairs, ephemeral ports,
in-process signals, real timers, temp-path file I/O, and genuine
error paths (connection refused, FIN, RST, cancellation, timeout)
- test/doc/programs: complete programs; servers that would run
forever are compiled and linked but not executed (run_examples.py
covers the real examples' runtime behavior)
- tutorial pages excerpt the canonical example programs via tag
regions; tls_context_examples.cpp joins the example build so its
excerpts cannot rot
- page preambles ("Code snippets assume") render from the tagged
tops of the TUs that compile them, so stated assumptions stay
honest
- @antora/collector-extension, registered in the library's own
playbook, scans example/ and test/doc into the Antora examples
family; pages use include::example$...[tag=...]
- blocks that intentionally do not compile are explicit:
role=pseudocode (6) and role=external (2)
- snippet_check.py is retired: extraction-based checking is obsolete
when the docs render from sources the test suite compiles and runs
|
An automated preview of the documentation is available at https://326.corosio.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-07-24 13:24:48 UTC |
|
GCOVR code coverage report https://326.corosio.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-07-24 13:38:47 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #326 +/- ##
========================================
Coverage 77.47% 77.47%
========================================
Files 96 96
Lines 6868 6868
Branches 1652 1652
========================================
Hits 5321 5321
Misses 1055 1055
Partials 492 492 Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
2 participants
Replace all ~375 hand-typed [source,cpp] blocks across the 30 doc pages with includes of compiled sources, mirroring Boost.Capy, so an example that breaks can no longer render on the site.