Fix DocFx configuration and build

- Bump DocFx version to 2.59.3 (fixes #1992)
- Build BDN before building docs (fixes xref issues)
- Add <ProduceReferenceAssembly> to BDN and BDN.Annotations projects (fixes xref issues)
- Add filter.yml to avoid listing inherited members of System.Object for each type.
- Add xrefService for resolving references to .NET SDK types.

Author: mawosoft

build/Program.cs

@@ -202,7 +202,7 @@ public void RunDocfx(FilePath docfxJson, string args = "")
 
 public static class DocumentationHelper
 {
-    public const string DocFxVersion = "2.57.2";
+    public const string DocFxVersion = "2.59.3";
 
     public static readonly string[] BdnAllVersions =
     {
@@ -454,6 +454,7 @@ public override void Run(BuildContext context)
 }
 
 [TaskName("DocFX_Build")]
+[IsDependentOn(typeof(BuildTask))] // Required to fix dofx xref issues
 [IsDependentOn(typeof(DocfxInstallTask))]
 [IsDependentOn(typeof(DocfxChangelogGenerateTask))]
 public class DocfxChangelogBuildTask : FrostingTask<BuildContext>

docs/docfx.json

@@ -15,6 +15,7 @@
         }
       ],
       "dest": "api",
+      "filter": "filter.yml",
       "properties": {
         "TargetFramework": "netstandard2.0"
       },
@@ -55,6 +56,9 @@
       "default",
       "template"
     ],
+    "xrefService": [
+      "https://xref.docs.microsoft.com/query?uid={uid}"
+    ],
     "postProcessors": ["ExtractSearchIndex"],
     "markdownEngineName": "markdig",
     "noLangKeyword": false,

docs/filter.yml

@@ -0,0 +1,4 @@
+apiRules:
+- exclude:
+    uidRegex: ^System\.Object
+    type: member # Avoid list of inherited Object members for each type.

src/BenchmarkDotNet.Annotations/BenchmarkDotNet.Annotations.csproj

@@ -7,6 +7,8 @@
     <AssemblyName>BenchmarkDotNet.Annotations</AssemblyName>
     <PackageId>BenchmarkDotNet.Annotations</PackageId>
     <RootNamespace>BenchmarkDotNet</RootNamespace>
+    <!-- needed for docfx xref resolver -->
+    <ProduceReferenceAssembly>True</ProduceReferenceAssembly>
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="..\BenchmarkDotNet\Helpers\CodeAnnotations.cs" Link="Attributes\CodeAnnotations.cs" />

src/BenchmarkDotNet/BenchmarkDotNet.csproj

@@ -8,6 +8,8 @@
     <AssemblyName>BenchmarkDotNet</AssemblyName>
     <PackageId>BenchmarkDotNet</PackageId>
     <RootNamespace>BenchmarkDotNet</RootNamespace>
+    <!-- needed for docfx xref resolver -->
+    <ProduceReferenceAssembly>True</ProduceReferenceAssembly>
   </PropertyGroup>
   <ItemGroup>
     <EmbeddedResource Include="Templates\*" Exclude="bin\**;obj\**;**\*.xproj;packages\**;@(EmbeddedResource)" />