feat: memberpage plugin -> memberLayout.SeparatePages (#8569)

docfx.sln

@@ -64,14 +64,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Common.
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Glob.Tests", "test\Microsoft.DocAsCode.Glob.Tests\Microsoft.DocAsCode.Glob.Tests.csproj", "{A95C5BAE-1D0D-44FD-A984-7CBF055A62E2}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Build.MemberLevelManagedReference", "plugins\Microsoft.DocAsCode.Build.MemberLevelManagedReference\Microsoft.DocAsCode.Build.MemberLevelManagedReference.csproj", "{2746DA6E-D310-4F07-B41B-929BB3D6E14B}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Plugins.Tests", "test\Microsoft.DocAsCode.Plugins.Tests\Microsoft.DocAsCode.Plugins.Tests.csproj", "{B3EEB5FE-CF39-4CC7-9650-5709E71D2BA9}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Build.ManagedReference.Tests", "test\Microsoft.DocAsCode.Build.ManagedReference.Tests\Microsoft.DocAsCode.Build.ManagedReference.Tests.csproj", "{958DF90F-0528-4C50-9AC2-E86C60971B7D}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Build.ManagedReference.WithPlugins.Tests", "test\Microsoft.DocAsCode.Build.ManagedReference.WithPlugins.Tests\Microsoft.DocAsCode.Build.ManagedReference.WithPlugins.Tests.csproj", "{958DF90F-0528-4C53-9AC2-E86C60971B7D}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "docfx", "src\docfx\docfx.csproj", "{EF53214F-BA98-4026-BEED-CF771865C312}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.DocAsCode.Build.UniversalReference.Tests", "test\Microsoft.DocAsCode.Build.UniversalReference.Tests\Microsoft.DocAsCode.Build.UniversalReference.Tests.csproj", "{E9795C9A-1F98-4716-A0FC-843C6B000BE5}"
@@ -382,18 +378,6 @@ Global
 		{A95C5BAE-1D0D-44FD-A984-7CBF055A62E2}.Release|x64.Build.0 = Release|Any CPU
 		{A95C5BAE-1D0D-44FD-A984-7CBF055A62E2}.Release|x86.ActiveCfg = Release|Any CPU
 		{A95C5BAE-1D0D-44FD-A984-7CBF055A62E2}.Release|x86.Build.0 = Release|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Debug|x64.Build.0 = Debug|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Debug|x86.Build.0 = Debug|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Release|Any CPU.Build.0 = Release|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Release|x64.ActiveCfg = Release|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Release|x64.Build.0 = Release|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Release|x86.ActiveCfg = Release|Any CPU
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B}.Release|x86.Build.0 = Release|Any CPU
 		{B3EEB5FE-CF39-4CC7-9650-5709E71D2BA9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{B3EEB5FE-CF39-4CC7-9650-5709E71D2BA9}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B3EEB5FE-CF39-4CC7-9650-5709E71D2BA9}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -418,18 +402,6 @@ Global
 		{958DF90F-0528-4C50-9AC2-E86C60971B7D}.Release|x64.Build.0 = Release|Any CPU
 		{958DF90F-0528-4C50-9AC2-E86C60971B7D}.Release|x86.ActiveCfg = Release|Any CPU
 		{958DF90F-0528-4C50-9AC2-E86C60971B7D}.Release|x86.Build.0 = Release|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Debug|x64.Build.0 = Debug|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Debug|x86.Build.0 = Debug|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Release|Any CPU.Build.0 = Release|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Release|x64.ActiveCfg = Release|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Release|x64.Build.0 = Release|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Release|x86.ActiveCfg = Release|Any CPU
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D}.Release|x86.Build.0 = Release|Any CPU
 		{EF53214F-BA98-4026-BEED-CF771865C312}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{EF53214F-BA98-4026-BEED-CF771865C312}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{EF53214F-BA98-4026-BEED-CF771865C312}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -722,10 +694,8 @@ Global
 		{05A49D39-97F0-46AF-9EDC-76D1E19FE3AC} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
 		{B2EEB5FE-CF39-4CC7-9650-5709E71D2BA9} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
 		{A95C5BAE-1D0D-44FD-A984-7CBF055A62E2} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
-		{2746DA6E-D310-4F07-B41B-929BB3D6E14B} = {DF2BA00B-1742-4F84-A469-08D7F019498E}
 		{B3EEB5FE-CF39-4CC7-9650-5709E71D2BA9} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
 		{958DF90F-0528-4C50-9AC2-E86C60971B7D} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
-		{958DF90F-0528-4C53-9AC2-E86C60971B7D} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
 		{EF53214F-BA98-4026-BEED-CF771865C312} = {6A65A769-DAC3-4E99-96F9-991F4CE8D164}
 		{E9795C9A-1F98-4716-A0FC-843C6B000BE5} = {926A0726-B806-4215-82EF-AF8E22D0FACF}
 		{FF8D61D0-01C9-44B9-98F9-37FCBF20CD72} = {6A65A769-DAC3-4E99-96F9-991F4CE8D164}

docs/docs/dotnet-api-docs.md

@@ -108,6 +108,18 @@ When the file extension is `.cs` or `.vb`, docfx uses the latest supported .NET
 }
 ```
 
+## Customization Options
+
+There are several options available for customizing .NET API pages that are tailored to your specific needs and preferences. To customize .NET API pages for DocFX, you can use the following options:
+
+- `memberLayout`: This option determines whether type members should be on the same page as containing type or as dedicated pages. Possible values are:
+  - `samePage`: Type members are on the same page as containing type.
+  - `separatePages`: Type members are on dedicated pages.
+
+- `namespaceLayout`: This option determines whether namespace node in TOC is a list or nested. Possible values are:
+  - `flattened`: Namespace node in TOC is a list.
+  - `nested`: Namespace node in TOC is nested.
+
 ## Supported XML Tags
 
 Docfx supports [Recommended XML tags for C# documentation comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags).

samples/extensions/README.md

@@ -1,6 +1,6 @@
 # Customize docfx with extensions
 
-This sample shows how to customize docfx with the `memberpage` extensions. It uses the `Microsoft.DocAsCode.App` package to build the project instead of using the global `docfx` commandline tool. To build the project, run the following command in this directory:
+This sample shows how to use docfx as a library. It uses the `Microsoft.DocAsCode.App` package to build the project instead of using the global `docfx` commandline tool. To build the project, run the following command in this directory:
 
 ```bash
 dotnet run --project build

samples/extensions/build/build.csproj

@@ -9,14 +9,12 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\src\Microsoft.DocAsCode.App\Microsoft.DocAsCode.App.csproj" />
-    <ProjectReference Include="..\..\..\plugins\Microsoft.DocAsCode.Build.MemberLevelManagedReference\Microsoft.DocAsCode.Build.MemberLevelManagedReference.csproj" />
   </ItemGroup>
 
   <!-- NOTE: Uncomment to use <PackageReference> for your own project. -->
   <!--
   <ItemGroup>
     <PackageReference Include="Microsoft.DocAsCode.App" Version="2.60.2" />
-    <PackageReference Include="Microsoft.DocAsCode.Build.MemberLevelManagedReference" Version="2.60.2" />
   </ItemGroup>
   -->
 

samples/extensions/docfx.json

@@ -11,7 +11,8 @@
       "dest": "api",
       "includePrivateMembers": true,
       "disableGitFeatures": false,
-      "disableDefaultFilter": false
+      "disableDefaultFilter": false,
+      "memberLayout": "separatePages"
     }
   ],
   "build": {
@@ -33,7 +34,7 @@
     "fileMetadataFiles": [],
     "template": [
       "default",
-      "memberpage"
+      "modern"
     ],
     "postProcessors": [],
     "keepFileLink": false,

plugins/Microsoft.DocAsCode.Build.MemberLevelManagedReference/SplitClassPageToMemberLevel.cs → src/Microsoft.DocAsCode.Build.ManagedReference/SplitClassPageToMemberLevel.cs

@@ -154,7 +154,7 @@ private SplittedResult SplitModelToOverloadLevel(FileModel model, Dictionary<str
 
         var page = (PageViewModel)model.Content;
 
-        if (page.Items.Count <= 1)
+        if (page.Items.Count <= 1 || page.MemberLayout != MemberLayout.SeparatePages)
         {
             return null;
         }

src/Microsoft.DocAsCode.Dotnet/DotnetApiCatalog.cs

@@ -123,7 +123,8 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config
             CodeSourceBasePath = configModel?.CodeSourceBasePath,
             DisableDefaultFilter = configModel?.DisableDefaultFilter ?? false,
             NoRestore = configModel?.NoRestore ?? false,
-            NamespaceLayout = configModel?.NamespaceLayout ?? NamespaceLayout.Flattened,
+            NamespaceLayout = configModel?.NamespaceLayout ?? default,
+            MemberLayout = configModel?.MemberLayout ?? default,
             AllowCompilationErrors = configModel?.AllowCompilationErrors ?? false,
             Files = expandedFiles.Items.SelectMany(s => s.Files).ToList(),
             References = expandedReferences?.Items.SelectMany(s => s.Files).ToList(),

src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs

@@ -27,6 +27,8 @@ internal class ExtractMetadataConfig
 
     public NamespaceLayout NamespaceLayout { get; init; }
 
+    public MemberLayout MemberLayout { get; init; }
+
     public Dictionary<string, string> MSBuildProperties { get; init; }
 
     public bool AllowCompilationErrors { get; init; }

src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs

@@ -222,7 +222,11 @@ private IEnumerable<string> ResolveAndExportYamlMetadata(
         model.TocYamlViewModel.Type = MemberType.Toc;
 
         // TOC do not change
-        var tocViewModel = model.TocYamlViewModel.ToTocViewModel();
+        var tocViewModel = new TocRootViewModel
+        {
+            Metadata = new() { ["memberLayout"] = _config.MemberLayout },
+            Items = model.TocYamlViewModel.ToTocViewModel(),
+        };
         string tocFilePath = Path.Combine(_config.OutputFolder, tocFileName);
 
         YamlUtility.Serialize(tocFilePath, tocViewModel, YamlMime.TableOfContent);
@@ -240,6 +244,7 @@ private IEnumerable<string> ResolveAndExportYamlMetadata(
             string itemFilePath = Path.Combine(_config.OutputFolder, outputFileName);
             var memberViewModel = memberModel.ToPageViewModel();
             memberViewModel.ShouldSkipMarkup = _config.ShouldSkipMarkup;
+            memberViewModel.MemberLayout = _config.MemberLayout;
             YamlUtility.Serialize(itemFilePath, memberViewModel, YamlMime.ManagedReference);
             Logger.Log(LogLevel.Diagnostic, $"Metadata file for {memberModel.Name} is saved to {itemFilePath}.");
             AddMemberToIndexer(memberModel, outputFileName, indexer);

src/Microsoft.DocAsCode.Dotnet/ManagedReference/PageViewModel.cs

@@ -26,6 +26,10 @@ public class PageViewModel
     [JsonProperty("shouldSkipMarkup")]
     public bool ShouldSkipMarkup { get; set; }
 
+    [YamlMember(Alias = "memberLayout")]
+    [JsonProperty("memberLayout")]
+    public MemberLayout MemberLayout { get; set; }
+
     [ExtensibleMember]
     [JsonExtensionData]
     public Dictionary<string, object> Metadata { get; set; } = new Dictionary<string, object>();