Merge remote-tracking branch 'upstream/main' into chore-fix-internal-…

…exception-on-toc-loading
dotnet · Jul 12, 2024 · 280054a · 280054a
2 parents 9d56541 + 156cf20
commit 280054a
Show file tree

Hide file tree

Showing 187 changed files with 1,499 additions and 1,438 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -4,3 +4,6 @@
 .xrefmap.json filter=lfs diff=lfs merge=lfs -text
 # Use LF for templates files.
 templates/** eol=lf
+
+# VerifyTests
+*.verified.txt text eol=lf working-tree-encoding=UTF-8
diff --git a/.github/actions/build/action.yml b/.github/actions/build/action.yml
@@ -20,5 +20,5 @@ runs:
     shell: bash
     working-directory: templates
 
-  - run: dotnet build -c Release --warnAsError
+  - run: dotnet build -c Release --warnAsError --maxcpucount
     shell: bash
diff --git a/.github/codeql-config.yml b/.github/codeql-config.yml
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -31,9 +31,9 @@ jobs:
       shell: bash
       working-directory: templates
 
-    - run: dotnet test -c Release -f net8.0 --no-build --collect:"XPlat Code Coverage"
+    - run: dotnet test -c Release -f net8.0 --no-build --collect:"XPlat Code Coverage" --consoleLoggerParameters:"Summary;Verbosity=Minimal"
 
-    - run: dotnet test -c Release -f net6.0 --no-build --collect:"XPlat Code Coverage"
+    - run: dotnet test -c Release -f net6.0 --no-build --collect:"XPlat Code Coverage" --consoleLoggerParameters:"Summary;Verbosity=Minimal"
       if: matrix.os == 'ubuntu-latest'
 
     - run: npm i -g @percy/cli
@@ -44,9 +44,6 @@ jobs:
       env:
         PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
 
-    - uses: codecov/codecov-action@v4
-      if: matrix.os == 'ubuntu-latest'
-
     - run: echo "DOTNET_DbgEnableMiniDump=1" >> $GITHUB_ENV
       if: matrix.os == 'ubuntu-latest'
 

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -16,9 +16,9 @@ jobs:
 
     - name: dotnet publish
       run: |
-        dotnet publish src/docfx -f net8.0 -c Release /p:Version=${GITHUB_REF_NAME#v} --self-contained -r win-x64 -o drop/publish/win-x64 /p:PlaywrightPlatform=win
-        dotnet publish src/docfx -f net8.0 -c Release /p:Version=${GITHUB_REF_NAME#v} --self-contained -r linux-x64 -o drop/publish/linux-x64 /p:PlaywrightPlatform=linux
-        dotnet publish src/docfx -f net8.0 -c Release /p:Version=${GITHUB_REF_NAME#v} --self-contained -r osx-x64 -o drop/publish/osx-x64 /p:PlaywrightPlatform=osx
+        dotnet publish src/docfx -f net8.0 -c Release /p:Version=${GITHUB_REF_NAME#v} --self-contained -r win-x64 -o drop/publish/win-x64
+        dotnet publish src/docfx -f net8.0 -c Release /p:Version=${GITHUB_REF_NAME#v} --self-contained -r linux-x64 -o drop/publish/linux-x64
+        dotnet publish src/docfx -f net8.0 -c Release /p:Version=${GITHUB_REF_NAME#v} --self-contained -r osx-x64 -o drop/publish/osx-x64
         mkdir -p drop/bin
 
     - run: zip -r ../../bin/docfx-win-x64-${GITHUB_REF_NAME}.zip .

diff --git a/Directory.Build.props b/Directory.Build.props
@@ -59,4 +59,12 @@
     </PackageReference>
   </ItemGroup>
 
+
+  <!-- Remove Node.js runtime dependencies that used by playwright -->
+  <Target Name="RemoveNodeJsRuntimes" AfterTargets="CopyPlaywrightFilesToOutput">
+    <ItemGroup>
+      <Content Remove="@(Content)" Condition="$([System.String]::Copy('%(Content.PlaywrightFolder)').Contains('node\'))" />
+    </ItemGroup>
+  </Target>
+
 </Project>
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -1,65 +1,65 @@
-<Project>
-  <!-- See https://learn.microsoft.com/nuget/consume-packages/Central-Package-Management -->
-  <PropertyGroup>
-    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
-  </PropertyGroup>
-  <ItemGroup>
-    <PackageVersion Include="HtmlAgilityPack" Version="1.11.61" />
-    <PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
-    <PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
-    <PackageVersion Include="Jint" Version="3.1.3" />
-    <PackageVersion Include="JsonSchema.Net" Version="7.0.4" />
-    <PackageVersion Include="Markdig" Version="0.37.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.271" />
-    <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
-    <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240612-d2cae" />
-    <PackageVersion Include="PlantUml.Net" Version="1.4.80" />
-    <PackageVersion Include="PolySharp" Version="1.14.1" />
-    <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.3.0" />
-  </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.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.10.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.10.0" />
-  </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.10.0" />
-    <PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
-    <PackageVersion Include="Verify.DiffPlex" Version="2.3.0" />
-    <PackageVersion Include="Verify.Xunit" Version="25.0.3" />
-    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.1" />
-    <PackageVersion Include="xunit" Version="2.8.1" />
-  </ItemGroup>
-</Project>
+<Project>
+  <!-- See https://learn.microsoft.com/nuget/consume-packages/Central-Package-Management -->
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="HtmlAgilityPack" Version="1.11.61" />
+    <PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
+    <PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
+    <PackageVersion Include="Jint" Version="3.1.4" />
+    <PackageVersion Include="JsonSchema.Net" Version="7.1.2" />
+    <PackageVersion Include="Markdig" Version="0.37.0" />
+    <PackageVersion Include="Microsoft.Playwright" Version="1.45.0" />
+    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
+    <PackageVersion Include="OneOf" Version="3.0.271" />
+    <PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
+    <PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240702-65c64" />
+    <PackageVersion Include="PlantUml.Net" Version="1.4.80" />
+    <PackageVersion Include="PolySharp" Version="1.14.1" />
+    <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.3.0" />
+  </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.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.10.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.10.0" />
+  </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.10.0" />
+    <PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
+    <PackageVersion Include="Verify.DiffPlex" Version="3.1.0" />
+    <PackageVersion Include="Verify.Xunit" Version="25.3.0" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="xunit" Version="2.9.0" />
+  </ItemGroup>
+</Project>
diff --git a/Dockerfile b/Dockerfile
@@ -3,18 +3,31 @@ FROM mcr.microsoft.com/dotnet/sdk:8.0-bookworm-slim
 # Add dotnet tools to path.
 ENV PATH="${PATH}:/root/.dotnet/tools"
 
+# Set target docfx version.
+ARG DOCFX_VERSION=2.77.0
+
 # Install DocFX as a dotnet tool.
-RUN dotnet tool update -g docfx && \
-    docfx --version
+RUN dotnet tool install docfx -g --version ${DOCFX_VERSION} && \
+    docfx --version && \
+    rm  -f /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/docfx.nupkg                         && \
+    rm  -f /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/docfx.${DOCFX_VERSION}.nupkg        && \
+    rm -rf /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net6.0
 
-# Install dependences for chromium PDF.
+# Install Node.js and dependences for chromium PDF.
 RUN apt-get update -qq && \
     apt-get install -y -qq --no-install-recommends \
+    nodejs \
     libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
     libdbus-1-3 libxcb1 libxkbcommon0 libatspi2.0-0 libx11-6 libxcomposite1 libxdamage1 \
     libxext6 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2 && \
     rm -rf /var/lib/apt/lists/* /tmp/*
 
+# Install Chromium.
+RUN PLAYWRIGHT_NODEJS_PATH="/usr/bin/node" && \
+    ln -s /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/.playwright /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/.playwright && \
+    pwsh -File /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/playwright.ps1 install chromium && \
+    unlink /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/.playwright
+
 WORKDIR /opt/prj
 VOLUME [ "/opt/prj" ]
 

diff --git a/docs/docs/pdf.md b/docs/docs/pdf.md
@@ -85,7 +85,7 @@ Indicates whether to include background graphics when rendering the pdf.
 
 ### `pdfHeaderTemplate`
 
-HTML template for the print header. Should be valid HTML markup with following HTML elements used to inject printing values into them:
+HTML template for the print header, or a path to an HTML page relative to the root of the output directory. Should be valid HTML markup with following HTML elements used to inject printing values into them:
 
 - `<span class='pageNumber'></span>`: current page number.
 - `<span class='totalPages'></span>`: total pages in the document.
@@ -95,7 +95,7 @@ HTML template for the print header. Should be valid HTML markup with following H
 
 ### `pdfFooterTemplate`
 
-HTML template for the print footer. Should use the same format as the [header template](#pdfheadertemplate). Uses the following default footer template if unspecified:
+HTML template for the print footer, or a path to an HTML page relative to the root of the output directory. Should use the same format as the [header template](#pdfheadertemplate). Uses the following default footer template if unspecified:
 
 ```html
 <div style="width: 100%; font-size: 12px;">

diff --git a/docs/reference/docfx-cli-reference/docfx-metadata.md b/docs/reference/docfx-cli-reference/docfx-metadata.md
@@ -95,11 +95,19 @@ Run `docfx metadata --help` or `docfx -h` to get a list of all available options
   - `SeparatePages`
     - Place members in separate pages.
 
+- **--useClrTypeNames**
+
+  Indicates whether the CLR type names or the language aliases must be used.
+
+    - not specified or `false`
+        - The language aliases are used: `int`.
+    - `true`
+        - The CLR type names are used: `Int32`.
+
 ## Examples
 
 - Generate YAML files with default config.
 
 ```pwsh
 docfx metadata
 ```
-
diff --git a/docs/reference/docfx-environment-variables-reference.md b/docs/reference/docfx-environment-variables-reference.md
@@ -26,4 +26,9 @@ This setting is intended to be used on offline environment.
 
 ## `DOCFX_PDF_TIMEOUT`
 
-Maximum time in milliseconds to override the default [Playwright timeout](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) for PDF generation.
+Maximum time in milliseconds to override the default [Playwright timeout](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout) for PDF generation.
+
+## `PLAYWRIGHT_NODEJS_PATH`
+
+Custom Node.js executable path that will be used by the `docfx pdf' command.
+By default, docfx automatically detect installed Node.js from `PATH`.
diff --git a/docs/tutorial/howto_add_a_customized_post_processor.md b/docs/tutorial/howto_add_a_customized_post_processor.md
@@ -9,8 +9,7 @@ In this topic, we will show how to add a customized post-processor.
 
 * Create a new C# class library project in `Visual Studio`.
 * Add nuget packages:
-    * [`System.Collections.Immutable`](https://www.nuget.org/packages/System.Collections.Immutable/1.3.1) with version 1.3.1
-    * [`Microsoft.Composition`](https://www.nuget.org/packages/Microsoft.Composition/1.0.31) with version 1.0.31
+    * [`System.Composition`](https://www.nuget.org/packages/System.Composition/8.0.0) with version 8.0.0
 * Add `Docfx.Plugins`
 If you are building DocFX from source code, add this reference to the project,
 otherwise add the nuget package `Docfx.Plugins` with the same version as DocFX.
@@ -58,8 +57,8 @@ Using `ExtractSearchIndex` for example again, we traverse all HTML files, extrac
 
 ## Step4: Build your project and copy the output dll files to:
 
-* Global: the folder with name `Plugins` under the folder containing the Docfx executable
-* Non-global: the folder with name `Plugins` under a template folder, then run `DocFX build` command with parameter `-t {template}`.
+* Global: the folder that contains the Docfx executable.
+* Non-global: the folder with name `plugins` under a template folder, then run `DocFX build` command with parameter `-t {template}`.
 
     *Hint*: DocFX can merge templates, so we can specify multiple template folders as `DocFX build -t {templateForRender},{templateForPlugins}`. Each of the template folders should have a subfolder named `Plugins` with exported assemblies.
 

diff --git a/schemas/docfx.schema.json b/schemas/docfx.schema.json
@@ -399,6 +399,7 @@
     "sitemap": {
       "type": "object",
       "description": "Specifies the options for the sitemap.xml file.",
+      "additionalProperties": false,
       "properties": {
         "baseUrl": {
           "type": "string",
@@ -465,6 +466,7 @@
     "markdownEngineProperties": {
       "description": "Set the parameters for markdown engine, value should be a JSON string.",
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "enableSourceInfo": {
           "type": "boolean",
@@ -520,6 +522,7 @@
     "plantUmlOptions": {
       "type": "object",
       "description": "PlantUml extension configuration parameters",
+      "additionalProperties": false,
       "properties": {
         "javaPath": {
           "type": "string",
@@ -572,6 +575,7 @@
       "type": "array",
       "items": {
         "type": "object",
+        "additionalProperties": false,
         "properties": {
           "src": {
             "$ref": "#/$defs/srcFileMapping"
@@ -688,6 +692,11 @@
             "type": "boolean",
             "default": false,
             "description": "When enabled, continues documentation generation in case of compilation errors."
+          },
+          "useClrTypeNames": {
+            "type": "boolean",
+            "default": false,
+            "description": "When enabled, use CLR type names instead of language aliases."
           }
         }
       }
@@ -742,6 +751,7 @@
       "type": "array",
       "items": {
         "type": "object",
+        "additionalProperties": false,
         "properties": {
           "content": {
             "$ref": "#/$defs/contentFileMapping"