Merge remote-tracking branch 'origin/feat/xml-error-reporting' into f…

…eat/xml-error-reporting

.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
  branches: [ main, feature/*, hotfix/* ]
  push:
  branches: [ main, feature/*, hotfix/* ]
+ workflow_dispatch:
 
 jobs:
  test:
@@ -32,9 +33,6 @@ jobs:
 
  - run: dotnet test -c Release -f net8.0 --no-build --collect:"XPlat Code Coverage"
 
- - run: dotnet test -c Release -f net7.0 --no-build --collect:"XPlat Code Coverage"
- if: matrix.os == 'ubuntu-latest'
-
  - run: dotnet test -c Release -f net6.0 --no-build --collect:"XPlat Code Coverage"
  if: matrix.os == 'ubuntu-latest'
 

.github/workflows/nightly.yml

@@ -3,13 +3,21 @@ on:
  schedule:
  - cron: '0 0 * * *'
 
+env:
+ DOCFX_PREVIEW_BUILD: true
+
 jobs:
  publish-github-packages:
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  permissions:
  packages: write
  steps:
+ - uses: actions/setup-dotnet@v4
+ with:
+ dotnet-version: |
+ 9.x
+
  - uses: actions/checkout@v4
  with:
  fetch-depth: 0
@@ -20,9 +28,12 @@ jobs:
  version_format: ${major}.${minor}.${patch}-preview.${increment}
 
  - uses: ./.github/actions/build
+
+ - name: dotnet test
+ run: dotnet test -c Release -f net9.0 --no-build
 
  - name: dotnet pack
- run: dotnet pack -c Release /p:Version=${{ steps.version.outputs.version }} -o drop/nuget
+ run: dotnet pack -c Release /p:Version=${{ steps.version.outputs.version }} /p:ApiCompatGenerateSuppressionFile=true -o drop/nuget
 
  - name: dotnet nuget push
  run: |

.github/workflows/release.yml

@@ -51,7 +51,7 @@ jobs:
  name: nuget
  path: drop/nuget
 
- - run: dotnet tool install --tool-path . sign --version 0.9.1-beta.23530.1
+ - run: dotnet tool install --tool-path . sign --version 0.9.1-beta.24170.3
 
  - run: >
  ./sign code azure-key-vault

Directory.Build.props

@@ -1,8 +1,8 @@
 <Project>
  <PropertyGroup>
  <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
- <TargetFrameworks>net6.0;net7.0;net8.0</TargetFrameworks>
- <!--<TargetFrameworks Condition=" '$(ContinuousIntegrationBuild)' == 'true' ">$(TargetFrameworks);net9.0</TargetFrameworks>-->
+ <TargetFrameworks>net6.0;net8.0</TargetFrameworks>
+ <TargetFrameworks Condition="'$(DOCFX_PREVIEW_BUILD)' == 'true'">net8.0;net9.0</TargetFrameworks> 
  <LangVersion>Preview</LangVersion>
  <ImplicitUsings>enable</ImplicitUsings>
  <SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>
@@ -17,9 +17,11 @@
  <!--
  Suppress warnings similar to the following:
  warning NU1507: There are 2 package sources defined in your configuration.
+ warning NU5104: A stable release of a package should not have a prerelease dependency. Either modify the version spec of dependency "PdfPig [0.1.9-alpha-20240510-d86c2, )" or update the version field in the nuspec.
+ warning NU5111: The script file 'tools\.playwright\package\bin\install_media_pack.ps1' is not recognized by NuGet and hence will not be executed during installation of this package.
  warning CS0436: IgnoresAccessChecksTo redefinition due to InternalsVisibleTo
  -->
- <NoWarn>$(NoWarn);NU1507;CS0436</NoWarn>
+ <NoWarn>$(NoWarn);NU1507;NU5104;NU5111;CS0436</NoWarn>
  </PropertyGroup>
 
  <PropertyGroup>

Directory.Packages.props

@@ -8,36 +8,56 @@
  <PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
  <PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
  <PackageVersion Include="Jint" Version="3.1.0" />
- <PackageVersion Include="JsonSchema.Net" Version="6.1.2" />
+ <PackageVersion Include="JsonSchema.Net" Version="7.0.2" />
  <PackageVersion Include="Markdig" Version="0.37.0" />
- <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.9.2" />
- <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.9.2" />
- <PackageVersion Include="Microsoft.Playwright" Version="1.43.0" />
+ <PackageVersion Include="Microsoft.Playwright" Version="1.44.0" />
  <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
  <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
- <PackageVersion Include="OneOf" Version="3.0.263" />
- <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.263" />
- <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240429-7f42a" />
+ <PackageVersion Include="OneOf" Version="3.0.271" />
+ <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
+ <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240510-d86c2" />
  <PackageVersion Include="PlantUml.Net" Version="1.4.80" />
  <PackageVersion Include="Spectre.Console" Version="0.49.1" />
  <PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
  <PackageVersion Include="Stubble.Core" Version="1.10.8" />
  <PackageVersion Include="System.Collections.Immutable" Version="8.0.0" />
  <PackageVersion Include="System.Composition" Version="8.0.0" />
- <PackageVersion Include="YamlDotNet" Version="15.1.2" />
+ <PackageVersion Include="YamlDotNet" Version="15.1.4" />
+ </ItemGroup>
+
+ <ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
+ <!-- "17.3.2" is the latest compatible version for .NET 6 -->
+ <PackageVersion Include="Microsoft.Build" Version="[17.3.2]" />
+ <PackageVersion Include="Microsoft.Build.Locator" Version="1.7.8" />
+ <PackageVersion Include="Microsoft.CodeAnalysis" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="[4.8.0]" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="[4.8.0]" />
+ </ItemGroup>
+
+ <ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
+ <PackageVersion Include="Microsoft.CodeAnalysis" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.9.2" />
+ <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.9.2" />
+ </ItemGroup>
+
+ <ItemGroup>
  <!-- Test only -->
  <PackageVersion Include="coverlet.collector" Version="6.0.2" />
  <PackageVersion Include="FluentAssertions" Version="6.12.0" />
- <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+ <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
  <PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
  <PackageVersion Include="Verify.DiffPlex" Version="2.3.0" />
- <PackageVersion Include="Verify.Xunit" Version="24.1.0" />
+ <PackageVersion Include="Verify.Xunit" Version="24.2.0" />
  <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.0" />
  <PackageVersion Include="xunit" Version="2.8.0" />
  </ItemGroup>

README.md

@@ -49,7 +49,7 @@ We welcome code contributions through pull requests, issues tagged as **[`help-w
 ### Prerequisites
 
 - Install [Visual Studio 2022 (Community or higher)](https://www.visualstudio.com/) and make sure you have the latest updates.
-- Install [.NET SDK](https://dotnet.microsoft.com/download/dotnet) 6.x, 7.x and 8.x.
+- Install [.NET SDK](https://dotnet.microsoft.com/download/dotnet) 6.x and 8.x.
 - Install NodeJS (20.x.x).
 
 ### Build and Test

docs/reference/docfx-json-reference.md

@@ -346,6 +346,7 @@ Specifies the output folder of the generated metadata files relative to `docfx.j
 Specifies the generated output file format.
 
 - `mref` (default): output as ManagedReference YAML files.
+- `apiPage`: Output as ApiPage YAML files.
 - `markdown`: Output as common-mark compliant markdown file.
 
 ### `dest`
@@ -433,6 +434,10 @@ Specifies whether private or internal APIs are included in the generated docs. T
 
 Specifies whether explicit interface implementations are included in the generated docs. The default value is `false`.
 
+### `globalNamespaceId`
+
+Specify the name to use for the global namespace. The default value is an empty string.
+
 ## File Mappings
 
 In the short-hand form, these filenames are resolved relative to the directory containing the `docfx.json` file:

src/Docfx.App/Docfx.App.csproj

@@ -7,7 +7,7 @@
 
  <ItemGroup>
  <Content Include="templates/**" CopyToOutputDirectory="PreserveNewest" PackageCopyToOutput="true" PackagePath="contentFiles/any/any/templates" />
- <None Include="Build\docfx.app.props" Pack="true" PackagePath="build\" />
+ <None Include="Build\Docfx.App.props" Pack="true" PackagePath="build/" />
  </ItemGroup>
 
  <ItemGroup>

src/Docfx.Build/HostServiceCreator.cs

@@ -63,12 +63,8 @@ public virtual (FileModel model, bool valid) Load(
  {
  if (e is not DocumentException)
  {
- var message = e is ArgumentException or NullReferenceException
- ? e.ToString()
- : e.Message;
-
  Logger.LogError(
- $"Unable to load file '{file.File}' via processor '{processor.Name}': {message}",
+ $"Unable to load file '{file.File}' via processor '{processor.Name}': {e.Message}",
  code: ErrorCodes.Build.InvalidInputFile);
  }
  return (null, false);

src/Docfx.Build/PostProcessors/PostProcessorsManager.cs

@@ -16,7 +16,6 @@ class PostProcessorsManager : IDisposable
  public PostProcessorsManager(CompositionHost container, ImmutableArray<string> postProcessorNames)
  {
  ArgumentNullException.ThrowIfNull(container);
- ArgumentNullException.ThrowIfNull(postProcessorNames);
 
  _postProcessors = GetPostProcessor(container, postProcessorNames);
  }

src/Docfx.Dotnet/Docfx.Dotnet.csproj

@@ -28,6 +28,11 @@
  <ProjectReference Include="..\Docfx.Plugins\Docfx.Plugins.csproj" />
  </ItemGroup>
 
+ <ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
+ <PackageReference Include="Microsoft.Build" ExcludeAssets="runtime" />
+ <PackageReference Include="Microsoft.Build.Locator" />
+ </ItemGroup>
+
  <ItemGroup>
  <PackageReference Include="HtmlAgilityPack" />
  <PackageReference Include="ICSharpCode.Decompiler" />

src/Docfx.Dotnet/DotnetApiCatalog.cs

@@ -57,6 +57,8 @@ internal static async Task Exec(MetadataJsonConfig config, DotnetApiOptions opti
  {
  var stopwatch = Stopwatch.StartNew();
 
+ EnsureMSBuildLocator();
+
  try
  {
  string originalGlobalNamespaceId = VisitorHelper.GlobalNamespaceId;
@@ -122,6 +124,26 @@ void WriteYaml(string outputFolder, string id, Build.ApiPage.ApiPage apiPage)
  }
  }
 
+ private static void EnsureMSBuildLocator()
+ {
+#if NET6_0
+ try
+ {
+ if (!Microsoft.Build.Locator.MSBuildLocator.IsRegistered)
+ {
+ var vs = Microsoft.Build.Locator.MSBuildLocator.RegisterDefaults() ?? throw new Docfx.Exceptions.ExtractMetadataException(
+ $"Cannot find a supported .NET Core SDK. Install .NET Core SDK {Environment.Version.Major}.{Environment.Version.Minor}.x to build .NET API docs.");
+
+ Logger.LogInfo($"Using {vs.Name} {vs.Version}");
+ }
+ }
+ catch (Exception e)
+ {
+ throw new Docfx.Exceptions.ExtractMetadataException(e.Message, e);
+ }
+#endif
+ }
+
  private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig configModel, string configDirectory, string outputDirectory)
  {
  var projects = configModel.Src;

templates/.stylelintrc.json

@@ -11,6 +11,12 @@
  "ignoreFontFamilies": [
  "bootstrap-icons"
  ]
+ }],
+ "property-no-unknown": [ true, {
+ "ignoreProperties": [ "navigation" ]
+ }],
+ "scss/at-rule-no-unknown": [ true, {
+ "ignoreAtRules": [ "view-transition" ]
  }]
  }
 }

templates/default/toc.extension.js

@@ -2,14 +2,14 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 /**
- * This method will be called at the start of exports.transform in toc.html.js
+ * This method will be called at the start of exports.transform in toc.html.js and toc.json.js
  */
 exports.preTransform = function (model) {
  return model;
 }
 
 /**
- * This method will be called at the end of exports.transform in toc.html.js
+ * This method will be called at the end of exports.transform in toc.html.js and toc.json.js
  */
 exports.postTransform = function (model) {
  return model;

templates/default/toc.json.js

@@ -1,11 +1,20 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
+var extension = require('./toc.extension.js')
 
 exports.transform = function (model) {
 
+ if (extension && extension.preTransform) {
+ model = extension.preTransform(model);
+ }
+
  if (model.memberLayout === 'SeparatePages') {
  model = transformMemberPage(model);
  }
+
+ if (extension && extension.postTransform) {
+ model = extension.postTransform(model);
+ }
 
  for (var key in model) {
  if (key[0] === '_') {

templates/modern/src/docfx.scss

@@ -97,3 +97,13 @@ article {
  }
  }
 }
+
+@view-transition {
+ navigation: auto;
+}
+
+@media (prefers-reduced-motion) {
+ @view-transition {
+ navigation: none;
+ }
+}

templates/modern/src/toc.ts

@@ -29,11 +29,12 @@ export async function renderToc(): Promise<TocNode[]> {
  const tocFilterUrl = disableTocFilter ? '' : (localStorage?.getItem('tocFilterUrl') || '')
  let tocFilter = disableTocFilter ? '' : (localStorage?.getItem('tocFilter') || '')
 
- if (tocFilterUrl !== tocUrl.toString()) {
+ if (tocFilterUrl === '' || tocFilterUrl !== tocUrl.toString()) {
  tocFilter = ''
- localStorage?.setItem('tocFilterUrl', '')
- } else {
- localStorage?.setItem('tocFilterUrl', tocUrl.toString())
+ if (!disableTocFilter) {
+ localStorage?.setItem('tocFilter', '')
+ localStorage?.setItem('tocFilterUrl', tocUrl.toString())
+ }
  }
 
  const activeNodes = []