build: use one generate and check pattern for all examples - #1323
Open
gennaroprota wants to merge 3 commits into
Open
gennaroprota wants to merge 3 commits into
gennaroprota wants to merge 3 commits into
Conversation
This fixes a bug for which a Lua script that serialized a table, such as the search-index generator example writing its entries with `ctx.stringify`, produced the keys in an order that changed from run to run, so its output could not be compared with a committed copy. A Lua table has no order of its own, and `lua_next` walks it in one that depends on a hash seed Lua picks anew for each state. Both conversions from a Lua table to a DOM object, the one for a value passed to a DOM function or assigned to a DOM member and the one for a Handlebars helper's result, now insert its string keys in sorted order.
Contributor
|
| Scope | Lines Δ% | Lines Δ | Lines + | Lines - | Files Δ | Files + | Files ~ | Files ↔ | Files - |
|---|---|---|---|---|---|---|---|---|---|
| 📚 Examples | 93% | 524 | 308 | 216 | 31 | 2 | 11 | - | 18 |
| 🛠️ Source | 7% | 37 | 29 | 8 | 2 | - | 2 | - | - |
| Total | 100% | 561 | 337 | 224 | 33 | 2 | 13 | - | 18 |
Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)
🔝 Top Files
- examples/cmake/MrDocsExample.cmake (Examples): 115 lines Δ (+115 / -0)
- examples/cmake/run-example.cmake (Examples): 83 lines Δ (+83 / -0)
- examples/extensions/CMakeLists.txt (Examples): 56 lines Δ (+15 / -41)
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1323 +/- ##
========================================
Coverage 83.12% 83.12%
========================================
Files 35 35
Lines 3662 3662
Branches 844 844
========================================
Hits 3044 3044
Misses 410 410
Partials 208 208
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
The committed output of the data-driven jsonl example predates the reflection-driven Handlebars DOM (d3fc5d5), since which the `anchor` of a member is the member's own, as in `length` rather than `Point-length`. The Data-Driven Generators page includes the file, so it showed output MrDocs no longer produces.
Each example directory registered its tests its own way: mrdocs called from `add_test`, a run.sh driven through Bash, a Python checker with a test and a regeneration target of its own. Most tests only checked that the run succeeded, so an output the docs include could drift without any of them noticing, as it happened with the jsonl example. Add `mrdocs_add_example`, which runs an example from its own directory and compares the output the example commits with the run, with a target to update it, or, for an example that commits nothing, only checks that the run succeeds. Every example that runs the tool goes through it, and the run.sh scripts are all gone. Fixes cppalliance#1295.
gennaroprota
force-pushed
the
build/use_one_generate_and_check_pattern_for_all_examples
branch
from
September 25, 2026 10:01
10607b0 to
1c92ebc
Compare
|
An automated preview of the documentation is available at https://1323.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-09-25 10:10:13 UTC |
This branch has not been deployed
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.
Each example directory registered its tests its own way, and most tests only checked that the run succeeded. So an output the docs include could drift unnoticed, as it happened with the jsonl example.
This PR adds
mrdocs_add_example, and uses that for every example that runs MrDocs. It runs the example from its own directory and compares the files the example commits with the run's output. It also adds a target that updates those files. An example that commits no output only checks that the run succeeds.Changes
mrdocs_add_example. Thereport.pyscripts leave the comparison to it, and the run.sh scripts are all removed.mrdocs-example-<name>and update targetsmrdocs-update-example-<name>, plusmrdocs-update-examplesfor all of them.Testing
CI runs the example tests with ctest.
Documentation
The examples README explains how the examples are tested and updated. The Data-Driven Generators page now shows the jsonl output MrDocs actually produces.
Closes #1295.