feat: move template specializations and deduction guides off parent scope page

[gennaroprota]

Class template specializations, function template specializations, and deduction guides used to share the enclosing scope's listing with their primary template. Users have repeatedly reported this as confusing: vector and vector<int> appearing side by side in the namespace index reads as if they were independent siblings, and a primary's variants were nowhere on its own page.

Specializations now appear in a dedicated "Specializations" section on the primary's documentation page, and deduction guides in a "Deduction Guides" section on the deduced class's page. The parent scope's listing carries only the primary itself. An orphan specialization (one whose primary has been excluded from extraction) stays in the parent's listing so the index can still reach it.

The corpus is unchanged: XML output and consumers of the metadata schema see the same data as before. The new sections are derived in the presentation layer.

Closes issue #1154.

[danger skip docs].

---

Summary

Moves class template specializations, function template specializations, and deduction guides off the enclosing scope's listing and onto the primary template's own documentation page. Closes #1154.

Specializations and primaries used to share the enclosing scope's listing, so vector and vector<int> appeared side by side in the namespace index — readers reported this as confusing, since the two are not independent siblings, and the primary's own page did not mention its variants at all.

After this PR:

• Each primary's documentation page gains a "Specializations" section listing the specializations of that primary.
• Each deduced class's page gains a "Deduction Guides" section listing the guides that deduce it.
• The parent scope's listing carries only the primary, not its variants.
• An orphan specialization — one whose primary has been excluded from extraction — stays in the parent's listing, so the index can still reach it.

The corpus is unchanged: XML output and consumers of the metadata schema see exactly the same data as before. The new sections are derived in the presentation layer. The diff is therefore concentrated in src/lib/Metadata/DomCorpus.{cpp,hpp} (the derivation), a few Handlebars helpers in src/lib/Support/Handlebars.cpp, and the Handlebars templates under share/mrdocs/addons/ that render the new sections. Two metadata headers (Function.hpp, Record.hpp) gain small additions to expose the primary-to-specialization link the derivation needs.

Changes

• Source: Derivation logic in src/lib/Metadata/DomCorpus.cpp (+159) and the public include/mrdocs/Metadata/DomCorpus.hpp (+36). Supporting Handlebars helpers in src/lib/Support/Handlebars.cpp (+54). include/mrdocs/Metadata/Symbol/Function.hpp (+28) and Symbol/Record.hpp (+14) expose the primary-to-specialization relationship the derivation reads. Templates updated under share/mrdocs/addons/: common/partials/symbol/tranche.hbs (the per-tranche listing that no longer prints specializations alongside the primary), and the per-format adoc/partials/symbol.adoc.hbs and html/partials/symbol.html.hbs rendering the new "Specializations" / "Deduction Guides" sections.
• Tests: All exercised through golden tests; no separate unit tests added.
• Golden tests: ~65 HTML and adoc golden-test fixtures updated across test-files/golden-tests/symbols/, test-files/golden-tests/config/, test-files/golden-tests/templates/, test-files/golden-tests/javadoc/, and test-files/golden-tests/filters/ to reflect the new layout — specializations and deduction guides moved off parent listings and onto primary pages. No .xml fixtures change, by design: the corpus is unchanged. Each updated fixture is an intentional rendering change, not a regeneration.
• Breaking changes: None at the user-facing CLI; none in the XML output or metadata schema (consumers of the corpus see the same data). The rendered HTML / adoc output for templates changes — downstream tooling that scrapes the parent scope's listing and expects to find specializations alongside the primary will need to look on the primary's own page instead.

Testing

• The ~65 HTML and adoc golden fixtures are themselves the verification: each runs the full pipeline against a fixed .cpp input and asserts the resulting .html / .adoc byte-for-byte. The unchanged .xml fixtures act as a regression guard for the architectural claim — if the corpus accidentally starts depending on the presentation change, the XML golden tests would fail.
• No CI workflow changes needed — the existing golden-test job runs all of test-files/golden-tests/ on every build, so the new expectations stay enforced going forward.

Documentation

No user-facing documentation page is added ([danger skip docs]). The change is a layout / discoverability improvement for the generated documentation: it does not introduce a new option, flag, or configuration knob a user would need to look up. The new "Specializations" / "Deduction Guides" sections are self-describing in the rendered output.

[github-actions]

✨ Highlights

• 🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	88%	2477	1996	481	66	-	66	-	-
🛠️ Source	12%	330	323	7	8	-	8	-	-
Total	100%	2807	2319	488	74	-	74	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• test-files/golden-tests/symbols/record/class-template-specializations-1.html (Golden Tests): 352 lines Δ (+221 / -131)
• test-files/golden-tests/symbols/record/class-template-specializations-1.adoc (Golden Tests): 224 lines Δ (+136 / -88)
• test-files/golden-tests/symbols/record/class-template-specializations-3.html (Golden Tests): 179 lines Δ (+142 / -37)

Generated by 🚫 dangerJS against fb11020

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.12%. Comparing base (1fc06a0) to head (fb11020).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1199   +/-   ##
========================================
  Coverage    82.12%   82.12%           
========================================
  Files           33       33           
  Lines         3149     3149           
  Branches       734      734           
========================================
  Hits          2586     2586           
  Misses         387      387           
  Partials       176      176           

Flag	Coverage Δ
bootstrap	82.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1199.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-13 14:40:57 UTC