docs: overhaul the documentation and gate it in CI - #377
Open
mvandeberg wants to merge 1 commit into
Open
Conversation
Rewrites the narrative and reference documentation against the shipped
code, and adds the linting, baseline and CI machinery that keeps them
from drifting again.
Narrative pages (doc/modules/ROOT/pages)
* Correct factual defects across every chapter: phantom
ReadSource/WriteSink and Source/Sink/BufferSource hierarchies, the
"one virtual call per I/O operation" and unconditional heap-frame
claims, Corosio's backend count, the stream-concept count, the
compiler floor and stale -fcoroutines advice, strand::dispatch's
inline-resume condition, fuse's run loop, and seven build recipes
that linked a nonexistent target.
* Link first-mention API references through the cpp: macro instead of
retyping signatures, and delete the reproduced contracts and
interface sketches those links replace.
* Declare a Diátaxis :page-mode: per page genre, drop the chapter
skeletons, and rebuild each landing page.
* Apply a Simplified Technical English wording pass to every page and
heading.
* Add 8q.gui-integration with a compiled example under
example/gui-integration; move the Corosio echo-server example out to
Corosio.
Reference docstrings (include/boost/capy)
* Rewrite identity-shaped briefs to describe behavior.
* Specify await-effects contracts for when_all, when_any, task and
quitter, and document the awaiter and lock_guard members of
async_event, async_mutex, async_waker, immediate, quitter and task.
* Complete @PARAM, @return, @pre, thread-safety and memory-resource
lifetime coverage across full overload sets.
* Fix docstring examples that did not compile, and correct claims about
strand's on_work_started/finished, thread_pool's lazy start,
default-constructed UB, after-error behavior, release()
postconditions, and MutableBufferSequence conversion.
* Add the boost/capy/test.hpp umbrella header; exclude internal test
helpers from the reference via mrdocs.yml.
* Apply the same Simplified Technical English pass to header prose.
Doc-quality tooling (doc/lint, doc/.vale, .github/workflows/docs.yml)
* Vale configuration plus Capy styles: NoFluff, PartHeadings,
SentenceLength, SimpleTense, Terminology and an accept vocabulary.
* Node checkers under doc/lint: doc-lint, sentence-length,
mrdocs-warnings, run-a11y, docstring extraction, baseline authoring
and comparison, and a selftest with fixtures.
* baseline.json grandfathers existing violations so the gate fails only
on new ones. Docstrings are extracted from /// comments so the gates
see headers, not just .adoc.
* CI runs a blocking doc-quality gate on A1/A6/A7/B2/D2, MrDocs
warnings and C2/C4/C9/C10; every check fails closed when it collapses
to zero or its corpus was not regenerated. Accessibility (pa11y) and
the remaining rules report without blocking. A workflow_dispatch job
reseeds the baseline.
Doc tests (test/doc)
* Extend the compiled snippets and programs, build them
warnings-as-errors, and drop the snippets whose page sketches were
deleted.
Process artifacts
* DOC_IMPROVEMENT_PLAN.md, DOC_STYLE_GUIDE.md, DOC_AUDIT_REFERENCE.md,
DOC_REVIEW_FEEDBACK.md, DOC_AUDIT_PHASE4_EXIT.md, doc-worklist.md,
doc-xref-gaps.md, doc-rationale-classification.md and doc-prompts/
record the plan, the style rules, the audit method and the remaining
backlog.
Known state: the doc-quality job fails on purpose. Two accepted
sentence-length (C2) findings in when_any.hpp are not in the baseline;
the post-merge reseed grandfathers them. See doc/lint/README.md.
|
An automated preview of the documentation is available at https://377.capy.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-08-14 20:42:33 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #377 +/- ##
========================================
Coverage 98.09% 98.09%
========================================
Files 132 132
Lines 6288 6288
========================================
Hits 6168 6168
Misses 120 120
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 42 files with indirect coverage changes Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
|
GCOVR code coverage report https://377.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-08-14 20:59:43 UTC |
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.
Rewrites the narrative and reference documentation against the shipped code, and adds the linting, baseline and CI machinery that keeps them from drifting again.
Narrative pages (doc/modules/ROOT/pages)
Reference docstrings (include/boost/capy)
Doc-quality tooling (doc/lint, doc/.vale, .github/workflows/docs.yml)
Doc tests (test/doc)
Process artifacts
Known state: the doc-quality job fails on purpose. Two accepted sentence-length (C2) findings in when_any.hpp are not in the baseline; the post-merge reseed grandfathers them. See doc/lint/README.md.