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

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 relationship is stored in the corpus: each primary record or
function template carries the IDs of its specializations (and, for class
templates, of its deduction guides), and each specialization carries an
`IsSpecialization` flag. The lists are populated by a finalizer pass and
exposed via reflection, so the XML output gains matching
`<specializations>`, `<deduction-guides>`, and `<is-specialization>`
elements and the DOM/Handlebars layer renders the new sections through
plain field access.

Closes issue #1154.

Author: gennaroprota

include/mrdocs/Metadata/Symbol/Function.hpp

@@ -22,6 +22,7 @@
 #include <mrdocs/Metadata/Symbol/SymbolBase.hpp>
 #include <mrdocs/Metadata/Template.hpp>
 #include <mrdocs/Support/Describe.hpp>
+#include <mrdocs/Support/MapReflectedType.hpp>
 #include <string>
 #include <vector>
 
@@ -137,6 +138,36 @@ struct FunctionSymbol final
     */
     Optional<SymbolID> FunctionObjectImpl;
 
+    /** Whether this function is listed on its primary's page.
+
+        A presentation-layer flag set by `SpecializationFinalizer`
+        when *both* conditions hold:
+
+          1. This function is a template specialization (AST-local,
+             equivalent to `Template->specializationKind() != Primary`).
+          2. Its primary is being extracted in
+             @ref ExtractionMode::Regular (cross-symbol, needs the
+             corpus).
+
+        When set, the function is rendered in its primary's
+        "Specializations" section and suppressed from the parent
+        scope's listing. Orphan specializations (primary excluded
+        from extraction) fail condition 2 and keep the flag `false`,
+        so they remain reachable from the parent scope. The name
+        deliberately encodes the resulting placement rather than
+        the AST property in 1, which `Template` already exposes.
+    */
+    bool IsListedOnPrimary = false;
+
+    /** Specializations whose primary is this function.
+
+        Populated by `SpecializationFinalizer` with the IDs of
+        function-template specializations referring to this
+        function as their primary. Sorted by referent name
+        then ID.
+    */
+    std::vector<SymbolID> Specializations;
+
     //--------------------------------------------
 
     /** Construct a function symbol with its ID.
@@ -161,7 +192,8 @@ MRDOCS_DESCRIBE_STRUCT(
      IsNodiscard, IsExplicitObjectMemberFunction, Constexpr,
      OverloadedOperator, StorageClass, IsRecordMethod, IsVirtual,
      IsVirtualAsWritten, IsPure, IsConst, IsVolatile, IsFinal,
-     RefQualifier, Explicit, Attributes, FunctionObjectImpl)
+     RefQualifier, Explicit, Attributes, FunctionObjectImpl,
+     IsListedOnPrimary, Specializations)
 )
 
 /** Map a vector of parameters to a @ref dom::Value object.

include/mrdocs/Metadata/Symbol/Record.hpp

@@ -5,6 +5,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -74,6 +75,43 @@ struct RecordSymbol final
     */
     std::vector<FriendInfo> Friends;
 
+    /** Whether this record is listed on its primary's page.
+
+        A presentation-layer flag set by `SpecializationFinalizer`
+        when *both* conditions hold:
+
+          1. This record is a template specialization (AST-local,
+             equivalent to `Template->specializationKind() != Primary`).
+          2. Its primary is being extracted in
+             @ref ExtractionMode::Regular (cross-symbol, needs the
+             corpus).
+
+        When set, the record is rendered in its primary's
+        "Specializations" section and suppressed from the parent
+        scope's listing. Orphan specializations (primary excluded
+        from extraction) fail condition 2 and keep the flag `false`,
+        so they remain reachable from the parent scope. The name
+        deliberately encodes the resulting placement rather than
+        the AST property in 1, which `Template` already exposes.
+    */
+    bool IsListedOnPrimary = false;
+
+    /** Specializations whose primary is this record.
+
+        Populated by `SpecializationFinalizer` with the IDs of
+        class-template specializations referring to this record
+        as their primary. Sorted by referent name then ID.
+    */
+    std::vector<SymbolID> Specializations;
+
+    /** Deduction guides associated with this class template.
+
+        Populated by `SpecializationFinalizer` with the IDs of
+        deduction guides that deduce this record. Sorted by
+        referent name then ID.
+    */
+    std::vector<SymbolID> DeductionGuides;
+
     //--------------------------------------------
 
     /** Create a record symbol bound to an ID.
@@ -93,7 +131,8 @@ MRDOCS_DESCRIBE_STRUCT(
     RecordSymbol,
     (SymbolCommonBase<SymbolKind::Record>),
     (KeyKind, Template, IsTypeDef, IsFinal, IsFinalDestructor,
-     Bases, Derived, Interface, Friends)
+     Bases, Derived, Interface, Friends,
+     IsListedOnPrimary, Specializations, DeductionGuides)
 )
 
 /** Return the default accessibility for a record key kind.

mrdocs.rnc

@@ -370,7 +370,10 @@ grammar
             BaseInfo*,
             element derived { SymbolID }*,
             RecordInterface?,
-            FriendInfo*
+            FriendInfo*,
+            element is-listed-on-primary { Bool }?,
+            element specializations { SymbolID }*,
+            element deduction-guides { SymbolID }*
         }
 
     BaseInfo =
@@ -445,7 +448,9 @@ grammar
             element ref-qualifier { text }?,
             element explicit { text }?,
             element attributes { text }*,
-            element function-object-impl { SymbolID }?
+            element function-object-impl { SymbolID }?,
+            element is-listed-on-primary { Bool }?,
+            element specializations { SymbolID }*
         }
 
     #---------------------------------------------

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -145,6 +145,16 @@
 {{/each}}
 |===
 
+{{/if}}
+{{! Specializations of this primary template }}
+{{#if symbol.specializations}}
+{{>symbol/members-table members=symbol.specializations title="Specializations"}}
+
+{{/if}}
+{{! Deduction guides for this class template }}
+{{#if symbol.deductionGuides}}
+{{>symbol/members-table members=symbol.deductionGuides title="Deduction Guides"}}
+
 {{/if}}
 {{! Using symbols }}
 {{#if symbol.shadowDeclarations}}

share/mrdocs/addons/generator/common/partials/symbol/tranche.hbs

@@ -7,6 +7,10 @@
 
     Each value in the tranche is a list of symbols that belong to the tranche.
 
+    Template specializations and deduction guides are filtered out: they are
+    listed instead on the primary template's own page, via the dedicated
+    "Specializations" / "Deduction Guides" sections.
+
     Expected Context: {Tranche Object}
 
     Example:
@@ -17,21 +21,20 @@
 {{#if is-namespace}}
 {{>symbol/members-table members=tranche.namespaces title="Namespaces"}}
 {{>symbol/members-table members=tranche.namespaceAliases title="Namespace Aliases"}}
-{{>symbol/members-table members=(concat tranche.records tranche.typedefs) title=(concat (select label (concat label " ") "") "Types")}}
+{{>symbol/members-table members=(concat (filter_out tranche.records "isListedOnPrimary") tranche.typedefs) title=(concat (select label (concat label " ") "") "Types")}}
 {{>symbol/members-table members=tranche.enums title=(concat (select label (concat label " ") "") "Enums")}}
-{{>symbol/members-table members=tranche.functions title="Functions"}}
+{{>symbol/members-table members=(filter_out tranche.functions "isListedOnPrimary") title="Functions"}}
 {{>symbol/members-table members=tranche.variables title="Variables"}}
 {{>symbol/members-table members=tranche.concepts title="Concepts"}}
-{{>symbol/members-table members=tranche.guides title=(concat (select label (concat label " ") "") "Deduction Guides")}}
 {{>symbol/members-table members=tranche.usings title=(concat (select label (concat label " ") "") "Using Declarations")}}
 {{else}}
 {{>symbol/members-table members=tranche.namespaceAliases title="Namespace Aliases"}}
-{{>symbol/members-table members=(concat tranche.records tranche.typedefs) title=(concat (select label (concat label " ") "") "Types")}}
+{{>symbol/members-table members=(concat (filter_out tranche.records "isListedOnPrimary") tranche.typedefs) title=(concat (select label (concat label " ") "") "Types")}}
 {{>symbol/members-table members=tranche.enums title=(concat (select label (concat label " ") "") "Enums")}}
-{{>symbol/members-table members=tranche.functions title=(concat (select label (concat label " ") "") "Member Functions")}}
-{{>symbol/members-table members=tranche.staticFunctions title=(concat (select label (concat label " ") "") "Static Member Functions")}}
+{{>symbol/members-table members=(filter_out tranche.functions "isListedOnPrimary") title=(concat (select label (concat label " ") "") "Member Functions")}}
+{{>symbol/members-table members=(filter_out tranche.staticFunctions "isListedOnPrimary") title=(concat (select label (concat label " ") "") "Static Member Functions")}}
 {{>symbol/members-table members=tranche.variables title=(concat (select label (concat label " ") "") "Data Members")}}
 {{>symbol/members-table members=tranche.staticVariables title=(concat (select label (concat label " ") "") "Static Data Members")}}
 {{>symbol/members-table members=tranche.aliases title=(concat (select label (concat label " ") "") "Aliases")}}
 {{>symbol/members-table members=tranche.usings title=(concat (select label (concat label " ") "") "Using Declarations")}}
-{{/if}}
+{{/if}}

share/mrdocs/addons/generator/html/partials/symbol.html.hbs

@@ -192,6 +192,18 @@
 </table>
 </div>
 {{/if}}
+{{! Specializations of this primary template }}
+{{#if symbol.specializations}}
+<div>
+{{>symbol/members-table members=symbol.specializations title="Specializations"}}
+</div>
+{{/if}}
+{{! Deduction guides for this class template }}
+{{#if symbol.deductionGuides}}
+<div>
+{{>symbol/members-table members=symbol.deductionGuides title="Deduction Guides"}}
+</div>
+{{/if}}
 {{! Using symbols }}
 {{#if symbol.shadowDeclarations}}
 <div>

src/lib/CorpusImpl.cpp

@@ -16,6 +16,7 @@
 #include <lib/AST/MissingSymbolSink.hpp>
 #include <lib/AST/MrDocsFileSystem.hpp>
 #include <lib/Metadata/Finalizers/BaseMembersFinalizer.hpp>
+#include <lib/Metadata/Finalizers/SpecializationFinalizer.hpp>
 #include <lib/Metadata/Finalizers/DerivedFinalizer.hpp>
 #include <lib/Metadata/Finalizers/DocCommentFinalizer.hpp>
 #include <lib/Metadata/Finalizers/FunctionObjectFinalizer.hpp>
@@ -1078,6 +1079,14 @@ CorpusImpl::finalize()
         finalizer.build();
     }
 
+    // Populate primary -> specialization back-pointers
+    // and the deduction-guide lists on deduced records.
+    {
+        report::debug("  - Finalizing specializations");
+        SpecializationFinalizer finalizer(*this);
+        finalizer.build();
+    }
+
     // Sort members: this runs unconditionally because
     // the members of some symbol types are always sorted.
     {

src/lib/CorpusImpl.hpp

@@ -64,6 +64,7 @@ class CorpusImpl final : public Corpus
     friend class NamespacesFinalizer;
     friend class DerivedFinalizer;
     friend class FunctionObjectFinalizer;
+    friend class SpecializationFinalizer;
 
 public:
     /** Constructor.