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

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,27 @@ struct FunctionSymbol final
     */
     Optional<SymbolID> FunctionObjectImpl;
 
+    /** Whether this function is rendered on its primary's page.
+
+        Set by `SpecializationFinalizer` for function-template
+        specializations whose primary is being extracted in
+        @ref ExtractionMode::Regular. Such specializations are
+        listed in the primary's "Specializations" section and
+        suppressed from the parent scope's listing. Orphan
+        specializations (primary excluded from extraction) keep
+        the flag `false` so they remain reachable from the parent.
+    */
+    bool IsSpecialization = 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 +183,8 @@ MRDOCS_DESCRIBE_STRUCT(
      IsNodiscard, IsExplicitObjectMemberFunction, Constexpr,
      OverloadedOperator, StorageClass, IsRecordMethod, IsVirtual,
      IsVirtualAsWritten, IsPure, IsConst, IsVolatile, IsFinal,
-     RefQualifier, Explicit, Attributes, FunctionObjectImpl)
+     RefQualifier, Explicit, Attributes, FunctionObjectImpl,
+     IsSpecialization, 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,34 @@ struct RecordSymbol final
     */
     std::vector<FriendInfo> Friends;
 
+    /** Whether this record is rendered on its primary's page.
+
+        Set by `SpecializationFinalizer` for class-template
+        specializations whose primary is being extracted in
+        @ref ExtractionMode::Regular. Such specializations are
+        listed in the primary's "Specializations" section and
+        suppressed from the parent scope's listing. Orphan
+        specializations (primary excluded from extraction) keep
+        the flag `false` so they remain reachable from the parent.
+    */
+    bool IsSpecialization = 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 +122,8 @@ MRDOCS_DESCRIBE_STRUCT(
     RecordSymbol,
     (SymbolCommonBase<SymbolKind::Record>),
     (KeyKind, Template, IsTypeDef, IsFinal, IsFinalDestructor,
-     Bases, Derived, Interface, Friends)
+     Bases, Derived, Interface, Friends,
+     IsSpecialization, 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-specialization { 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-specialization { 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 (reject_by tranche.records "isSpecialization") 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=(reject_by tranche.functions "isSpecialization") 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 (reject_by tranche.records "isSpecialization") 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=(reject_by tranche.functions "isSpecialization") title=(concat (select label (concat label " ") "") "Member Functions")}}
+{{>symbol/members-table members=(reject_by tranche.staticFunctions "isSpecialization") 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.