feat: Add categoryLayout option for metadata generation (#9965)

feat: add categoryLayout options

Author: filzrev

docs/reference/docfx-json-reference.md

@@ -401,6 +401,17 @@ Specifies an optional set of MSBuild properties used when interpreting project f
 
 Do not run `dotnet restore` before building the projects.
 
+### `categoryLayout`
+
+Specifies how categories in TOC are organized:
+
+- `flattened` (default): Renders the namespaces as a plain label.
+- `nested`: Renders the categories in a nested tree form.
+- `none`: Don't render categoriy labels.
+
+> [!NOTE]
+> This setting is valid when using `apiPage` or `markdown` output format. `mref` format don't support categories.
+
 ### `namespaceLayout`
 
 Specifies how namespaces in TOC are organized:

schemas/docfx.schema.json

@@ -647,6 +647,16 @@
             "default": false,
             "description": "Do not run dotnet restore before building the projects."
           },
+          "categoryLayout": {
+            "type": "string",
+            "description": "Defines how categories in TOC are organized. This setting is valid when using `apiPage` or `markdown` output format. `mref` format don't support categories.",
+            "default": "flattened",
+            "enum": [
+              "flattened",
+              "nested",
+              "none"
+            ]
+          },
           "namespaceLayout": {
             "type": "string",
             "description": "Defines how namespaces in TOC are organized.",

src/Docfx.Dotnet/DotnetApiCatalog.Toc.cs

@@ -49,7 +49,7 @@ private static List<TocNode> CreateToc(List<(IAssemblySymbol symbol, Compilation
         var ext = config.OutputFormat is MetadataOutputFormat.Markdown ? ".md" : ".yml";
         var toc = assemblies.SelectMany(a => CreateToc(a.symbol.GlobalNamespace, a.compilation)).ToList();
 
-        SortToc(toc, root: true);
+        SortToc(toc, null);
 
         YamlUtility.Serialize(Path.Combine(config.OutputFolder, "toc.yml"), toc, YamlMime.TableOfContent);
         return toc;
@@ -211,11 +211,11 @@ IMethodSymbol method when SymbolHelper.IsOperator(method) => TocNodeType.Operato
             }
         }
 
-        static void SortToc(List<TocNode> items, bool root)
+        void SortToc(List<TocNode> items, TocNode? parentTocNode)
         {
             items.Sort((a, b) => a.type.CompareTo(b.type) is var r && r is 0 ? a.name.CompareTo(b.name) : r);
 
-            if (!root)
+            if (parentTocNode != null)
             {
                 InsertCategory(TocNodeType.Class, "Classes");
                 InsertCategory(TocNodeType.Struct, "Structs");
@@ -233,13 +233,43 @@ static void SortToc(List<TocNode> items, bool root)
             foreach (var item in items)
             {
                 if (item.items is not null)
-                    SortToc(item.items, root: false);
+                    SortToc(item.items, item);
             }
 
             void InsertCategory(TocNodeType type, string name)
             {
-                if (items.FirstOrDefault(i => i.type == type) is { } node)
-                    items.Insert(items.IndexOf(node), new() { name = name });
+                switch (config.CategoryLayout)
+                {
+                    // Don't insert category.
+                    case CategoryLayout.None:
+                        return;
+
+                    // Insert category as clickable TocNode.
+                    case CategoryLayout.Nested:
+                        {
+                            // Skip when parent node is category node.
+                            if (parentTocNode != null && parentTocNode.type == TocNodeType.None)
+                                return;
+
+                            // If items contains specified type node. Create new TocNode for category. and move related node to child node.
+                            if (items.FirstOrDefault(i => i.type == type) is { } node)
+                            {
+                                var head = new TocNode { name = name, items = items.Where(x => x.type == type).ToList() };
+                                items.Insert(items.IndexOf(node), head);
+                                items.RemoveAll(x => x.type == type);
+                            }
+                            return;
+                        }
+
+                    // Insert category as text label.
+                    case CategoryLayout.Flattened:
+                    default:                    
+                        {
+                            if (items.FirstOrDefault(i => i.type == type) is { } node)
+                                items.Insert(items.IndexOf(node), new() { name = name });
+                            return;
+                        }
+                }
             }
         }
     }

src/Docfx.Dotnet/DotnetApiCatalog.cs

@@ -162,6 +162,7 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config
             DisableDefaultFilter = configModel?.DisableDefaultFilter ?? false,
             DisableGitFeatures = configModel?.DisableGitFeatures ?? false,
             NoRestore = configModel?.NoRestore ?? false,
+            CategoryLayout = configModel?.CategoryLayout ?? default,
             NamespaceLayout = configModel?.NamespaceLayout ?? default,
             MemberLayout = configModel?.MemberLayout ?? default,
             EnumSortOrder = configModel?.EnumSortOrder ?? default,

src/Docfx.Dotnet/ManagedReference/ExtractMetadataConfig.cs

@@ -31,6 +31,8 @@ internal class ExtractMetadataConfig
 
     public bool NoRestore { get; init; }
 
+    public CategoryLayout CategoryLayout { get; init; }
+
     public NamespaceLayout NamespaceLayout { get; init; }
 
     public MemberLayout MemberLayout { get; init; }

src/Docfx.Dotnet/MetadataJsonConfig.cs

@@ -22,6 +22,27 @@ public enum MemberLayout
     SeparatePages,
 }
 
+/// <summary>
+/// Specifies the layout of categories.
+/// </summary>
+internal enum CategoryLayout
+{
+    /// <summary>
+    /// Renders the categories as a a plain label.
+    /// </summary>
+    Flattened,
+
+    /// <summary>
+    /// Renders the categories in a nested tree form.
+    /// </summary>
+    Nested,
+
+    /// <summary>
+    /// Don't render category labels.
+    /// </summary>
+    None,
+}
+
 /// <summary>
 /// Specifies the layout of namepsaces.
 /// </summary>
@@ -194,6 +215,16 @@ internal class MetadataJsonItemConfig
     [JsonPropertyName("noRestore")]
     public bool NoRestore { get; set; }
 
+    /// <summary>
+    /// Defines how categories in TOC are organized:
+    /// - `flattened` (default): Renders categories as a plain label.
+    /// - `nested`: Renders categories in a nested tree form.
+    /// - `none`: Don't render category labels.
+    /// </summary>
+    [JsonProperty("categoryLayout")]
+    [JsonPropertyName("categoryLayout")]
+    public CategoryLayout CategoryLayout { get; set; }
+
     /// <summary>
     /// Defines how namespaces in TOC are organized:
     /// - `flattened` (default): Renders namespaces as a single flat list.

src/docfx/Models/MetadataCommand.cs

@@ -27,6 +27,7 @@ private static void MergeOptionsToConfig(MetadataCommandOptions options, DocfxCo
             item.ShouldSkipMarkup |= options.ShouldSkipMarkup;
             item.DisableGitFeatures |= options.DisableGitFeatures;
             item.DisableDefaultFilter |= options.DisableDefaultFilter;
+            item.CategoryLayout = options.CategoryLayout ?? item.CategoryLayout;
             item.NamespaceLayout = options.NamespaceLayout ?? item.NamespaceLayout;
             item.MemberLayout = options.MemberLayout ?? item.MemberLayout;
             item.OutputFormat = options.OutputFormat ?? item.OutputFormat;

src/docfx/Models/MetadataCommandOptions.cs

@@ -45,6 +45,10 @@ internal class MetadataCommandOptions : LogOptions
     [CommandOption("--disableDefaultFilter")]
     public bool DisableDefaultFilter { get; set; }
 
+    [Description("Determines the category layout in table of contents.")]
+    [CommandOption("--categoryLayout")]
+    public CategoryLayout? CategoryLayout { get; set; }
+
     [Description("Determines the namespace layout in table of contents.")]
     [CommandOption("--namespaceLayout")]
     public NamespaceLayout? NamespaceLayout { get; set; }