docs: restructure, generated registry, and live snippets#1220
docs: restructure, generated registry, and live snippets#1220alandefreitas wants to merge 13 commits into
Conversation
|
| Scope | Lines Δ% | Lines Δ | Lines + | Lines - | Files Δ | Files + | Files ~ | Files ↔ | Files - |
|---|---|---|---|---|---|---|---|---|---|
| 🥇 Golden Tests | 62% | 27936 | 27894 | 42 | 449 | 433 | 16 | - | - |
| 📄 Docs | 18% | 8263 | 6450 | 1813 | 70 | 36 | 28 | 1 | 5 |
| 🛠️ Source | 14% | 6477 | 5050 | 1427 | 159 | 123 | 27 | 6 | 3 |
| 🧰 Tooling | 2% | 966 | 843 | 123 | 4 | 3 | - | - | 1 |
| 🧪 Unit Tests | 1% | 539 | 117 | 422 | 14 | 1 | 3 | - | 10 |
| 🔧 Toolchain | 1% | 522 | 486 | 36 | 7 | 2 | 5 | - | - |
| 🏗️ Build | <1% | 149 | 102 | 47 | 1 | - | 1 | - | - |
| ⚙️ CI | <1% | 107 | 50 | 57 | 7 | - | 6 | - | 1 |
| 🔧 Toolchain Tests | <1% | 17 | 13 | 4 | 1 | - | 1 | - | - |
| Total | 100% | 44976 | 41005 | 3971 | 712 | 598 | 87 | 7 | 20 |
Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)
🔝 Top Files
- src/lib/Metadata/DescribedObjectProxy.hpp (Source): 1149 lines Δ (+1149 / -0)
- docs/modules/ROOT/partials/commands-registry.json (Docs): 930 lines Δ (+930 / -0)
- src/lib/Extensions/SetMember.cpp (Source): 727 lines Δ (+0 / -727)
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1220 +/- ##
===========================================
- Coverage 82.12% 81.97% -0.15%
===========================================
Files 33 34 +1
Lines 3149 3179 +30
Branches 734 743 +9
===========================================
+ Hits 2586 2606 +20
- Misses 387 392 +5
- Partials 176 181 +5
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:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7544129ae8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
An automated preview of the documentation is available at https://1220.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-06-08 05:54:54 UTC |
Upstream context: codecov/codecov-action#1956
The Antora docs are reorganized to be more complete and goal-oriented: each topic lives in its own directory with more detailed pages; the reference content (commands and options) is generated from a single source of truth that the implementation reads; and all examples and the reference include live-tested examples. fix cppalliance#676
2 participants
This PR completely reorganizes and rewrites the documentation. The current documentation has issues that users keep raising. Commands and options lack reference sections, and much of the exposition is out of date. We also need to improve it because of the conference talks we've been preparing, since the website is the first thing a prospective user sees after a talk.
Changes
Almost everything in the diff serves the documentation. The Antora pages are reorganized so each topic owns its own directory, with more detailed subpages. The commands and options reference is now generated from a single source of truth. Every example in the documentation, both for commands and options, is paired with a runnable snippet and its expected output, which are now part of the tests. There are now inline previews for these snippets (like we already had for the landing page). The UI bundle now highlights documentation commands.
The file count looks high, mostly because of snippet fixtures and their golden outputs. Every documented option includes at least one snippet, the configuration that exercises it, and the rendered output we test. The same applies to the runnable examples. The exposition now includes complete examples to get started. The user can copy any of them to get started.
The remaining commits in this PR are not the focus of the work. While writing the goal-oriented pages, a few small problems with the tool kept getting in the way of writing useful examples that even made sense. Each fix has its own commit. They aren't feature requests in isolation. They were fixed because they were blocking the documentation.
Testing
This PR is precisely creating tests for snippets that weren't tested before or didn't exist.
Documentation
This PR is a documentation update. There is nothing further to update.