[Feature Request] Support custom API page categories

[glopesdev]

Is your feature request related to a problem? Please describe.

The API page output format is a great way to help organize large project reference documentation by grouping types into categories, e.g. Classes and Enums. However, in some domains it would be great to have support for additional custom groups, e.g. Attributes or TypeConverters.

Describe the solution you'd like

It would be great if there was a way to specify new custom categories, and provide filters for types to be included in them, e.g. similar to hasAttribute in filter.yml.

For example, in the YAML below we would be able to specify that all classes with the AttributeUsageAttribute would be grouped under a new custom API page type group called Attributes.

apiPages:
- groups:
  - name: Attributes 
    hasAttribute:
      uid: System.AttributeUsageAttribute

Describe alternatives you've considered

I have looked into the DocFX template system for ways to customize the left-hand side TOC and couldn't find anything that could be used to achieve this.

It is unclear from the current docs and template code how the grouping in the API page templates is even achieved in the current DocFX template system, but it could be another way to do it, as long as there are ways to specify the relevant conditionals.

Additional context

It looks like the current feature for API page output format might be implemented here:

docfx/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs

Lines 181 to 185 in 7734a89

	Types(t => t.TypeKind is TypeKind.Class, "Classes");
	Types(t => t.TypeKind is TypeKind.Struct, "Structs");
	Types(t => t.TypeKind is TypeKind.Interface, "Interfaces");
	Types(t => t.TypeKind is TypeKind.Enum, "Enums");
	Types(t => t.TypeKind is TypeKind.Delegate, "Delegates");

Apparently the t in this lambda is an instance of INamedTypeSymbol from the Roslyn analyzers. If this is the case, it should be possible to add additional predicates to test custom attributes using the ISymbol.GetAttributes method, e.g. something like:

Types(t => t.GetAttributes().Any(a => a.AttributeClass.Name == "System.AttributeUsageTarget"), "Attributes");

[filzrev]

I have looked into the DocFX template system for ways to customize the left-hand side TOC and couldn't find anything that could be used to achieve this.

TOC categories are inserted by following lines.

docfx/src/Docfx.Dotnet/DotnetApiCatalog.Toc.cs

Lines 220 to 230 in e5889cf

	InsertCategory(TocNodeType.Class, "Classes");
	InsertCategory(TocNodeType.Struct, "Structs");
	InsertCategory(TocNodeType.Interface, "Interfaces");
	InsertCategory(TocNodeType.Enum, "Enums");
	InsertCategory(TocNodeType.Delegate, "Delegates");
	InsertCategory(TocNodeType.Constructor, "Constructors");
	InsertCategory(TocNodeType.Field, "Fields");
	InsertCategory(TocNodeType.Property, "Properties");
	InsertCategory(TocNodeType.Method, "Methods");
	InsertCategory(TocNodeType.Event, "Events");
	InsertCategory(TocNodeType.Operator, "Operators");

TocNode contains symbols data so it can implement Custom Category feature by using this information.
Though it'll requires some code refactoring.

---

It looks like the current feature for API page output format might be implemented here:

Suggested code seems to be used for Namespace API pages. (e.g. https://dotnet.github.io/docfx/api/Docfx.html)