dotnet / dotnet/docfx

[Feature Request] Support custom API page categories

Open
#9,998 1 comment 0 reactions 0 assignees View on GitHub
dotnet
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

**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`.

```yaml
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:

https://github.com/dotnet/docfx/blob/7734a8912414ff6745ea96257f688625135c53fc/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs#L181-L185

Apparently the `t` in this lambda is an instance of [`INamedTypeSymbol`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.inamedtypesymbol?view=roslyn-dotnet-4.7.0) 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`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.isymbol.getattributes?view=roslyn-dotnet-4.7.0#microsoft-codeanalysis-isymbol-getattributes) method, e.g. something like:

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.