Document how to build, name the C++26 entry point, and fix the docs-site alerts - #395
Merged
Merged
Conversation
Assisted-by: Claude:claude-opus-5
Also drops the claim that libfn suits asynchronous composition. Nothing in the repository backs it: no example, no reference page, and the paragraph's one substantiated sentence — that an operation is a value, applied when a monad is piped into it — is already made where callables as values are discussed. Assisted-by: Claude:claude-opus-5
The site showed each of TYPE_ALGEBRA's fourteen alerts as a plain blockquote opening with a literal `[!NOTE]` line. The quoting comes off before the existing rewrites, so that a heading or a link inside an alert is treated like any other — the heading pattern is line-anchored and never matched a quoted one — and the block is fenced afterwards, longer than any fence it contains. znai builds an attention block for a fixed set of types and turns anything else into a code snippet that prints the markdown verbatim, which is how `attention-tip` passed a green build. An unmapped kind now fails the staging instead. `[!TIP]` maps to a note block, there being no `tip`; #394 covers giving the mathematical asides their own styling. Assisted-by: Claude:claude-opus-5
🤖 Augment PR SummarySummary: Improves the project’s documentation for the 0.1 release by making local build modes reproducible, documenting the C++26 entry point, and fixing docs-site rendering of GitHub-style alerts. Changes:
Technical Notes: The staging script now detects both backtick and tilde fences, fails staging on unknown alert kinds, and fences attention blocks longer than any internal backtick fence to avoid accidental termination. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
The alert scan walked the lines itself rather than through `outside_fences`, which this file has so that no rule fires on fenced content. A fence quoting `> [!NOTE]` as an example of the syntax therefore had its quoting stripped and markers planted inside the code. No document quotes it today, so nothing reached the site that way; the invariant is the point. Assisted-by: Claude:claude-opus-5
Member
Author
|
augment review |
A blockquote also swallows an unquoted line that merely continues its paragraph, and only a block of its own ends it. Ending the alert at every unquoted line would split such a body across the attention block, silently. No document does this today, so the conversion refuses the ambiguity rather than guessing at it. Assisted-by: Claude:claude-opus-5
Member
Author
|
augment review |
`outside_fences` recognised only backtick fences, so a `~~~` block was exposed to every rewrite the staging performs — links, headings and badges as much as alerts. It now tracks the marker that opened the fence and closes on that character alone, at a run no shorter, so a fence may quote a shorter one of either kind. No document uses tildes today; the staged output is unchanged. Assisted-by: Claude:claude-opus-5
Member
Author
|
augment review |
A block may carry three spaces of indent before it, so an alert marker away from column zero was read as ordinary prose and a slightly indented list or fence after one was read as a paragraph that had lost its quoting, failing the staging. Both now admit those three spaces, and a fourth still makes the line code rather than either. Assisted-by: Claude:claude-opus-5
Member
Author
|
augment review |
A closing fence carries no info string, so a line opening a nested fence of equal length is content, not the closer. Also state the recognizer's conservative scope in the module docstring. Assisted-by: Claude:claude-fable-5
CLAUDE.md gains the design gate, the documentation duty and the editing protocol; TYPE_ALGEBRA.md gains the document-guidelines contract, with a structural index as its checksum. The Assisted-by trailer folds into the existing convention, vendor-neutral, citing the kernel guidelines it follows. Assisted-by: Claude:claude-fable-5
Section 4's pointer to Section 6 lands on prose stating the equivalence, not on an inference from the example. The placeholder types join the quoted definitions block; only the sync markers move, the example code is unchanged. Assisted-by: Claude:claude-fable-5
Section 15 gains the ABI-namespace mechanism under its own name — one normalization order per program — and Section 2's note and README's loud-by-design sentence now point at it. README's What section gives the design document its billing. Subheadings settle on sentence case, choice<>'s incompleteness loses its circular phrasing, and the narrator's "we" goes. Assisted-by: Claude:claude-fable-5
|
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
1 participant
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.
Three documentation changes for the 0.1 release, one per commit.
Show how to configure each build.
CONTRIBUTING.mddescribed the CMake options in prose but gave nocmakeinvocation anywhere — the only runnable line in## Building locallycompiled a single example withg++. It now opens with the default configure, build andctest, and carries a section each for the C++23 and C++26 modes, sanitizers, coverage and the documentation build, with the requirements that are easy to get wrong:gcovr8.4 or newer and a coverage tool matching the compiler; Doxygen 1.12.0, znai 1.91 and Graphviz for the docs; and the platforms where sanitizers are refused outright.Name the C++26 entry point.
README.mdnamed onlylibfn::fnandlibfn::pfn, leavinglibfn::fn_cxx26undocumented for consumers. It now states the rule — link exactly one entry point per target — and what each way of getting it wrong looks like: the#errornaming__cpp_lib_type_order, and the undefined reference whose type names differ by the_cxx26ABI namespace. Part of #352.This commit also drops README's claim that libfn suits asynchronous composition. Nothing in the repository backed it, and the paragraph's one substantiated sentence is already made where callables as values are discussed. #393 tracks earning the claim back with an example.
Render GitHub's alerts as znai attention blocks. TYPE_ALGEBRA's fourteen
> [!NOTE]/> [!TIP]/> [!WARNING]alerts reached the documentation site as plain blockquotes, each opening with a literal[!NOTE]line.scripts/stage_docs_source.pynow converts them: the quoting comes off before the existing rewrites, so a heading or link inside an alert is treated like any other, and the block is fenced afterwards, longer than any fence it contains.znai builds an attention block for a fixed set of types and turns anything else into a code snippet that prints the markdown verbatim — which is how a first attempt using
attention-tipproduced a green build and a broken page. An unmapped alert kind now fails the staging instead.[!TIP]maps to a note block, there being notiptype; #394 covers giving the mathematical asides their own styling.Verification
The full documentation pipeline was run locally on this tree:
export_docsexits 0 through all six steps, includingdocs_check_coverageanddocs_check_signatures. All fourteen alerts convert, no literal GFM marker survives anywhere on the generated site, noBlockQuotenode remains, and the nestedcppexcerpt on the identity-cluster page still renders as a code snippet inside its attention block.On tests
No test accompanies the staging-script change. Testing the generated site would mean asserting against znai's output — a harness, a fixture format and a dependency aimed at the documentation toolchain rather than at the library's semantics, which is not a burden this project should take on. znai turns an unrecognised attention type into a code snippet without failing, so
export_docswas green both before this change and while it briefly emitted a brokenattention-tip; the script now fails staging on an alert kind it has no block for, which closes that silent path directly instead.Assisted-by: Claude:claude-opus-5