Skip to content

Commit 280054a

Browse files
filzrevfilzrev
committed
Merge remote-tracking branch 'upstream/main' into chore-fix-internal-exception-on-toc-loading
2 parents 9d56541 + 156cf20 commit 280054a

File tree

187 files changed

+1499
-1438
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

187 files changed

+1499
-1438
lines changed

‎.gitattributes

+3
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,6 @@
44
.xrefmap.json filter=lfs diff=lfs merge=lfs -text
55
# Use LF for templates files.
66
templates/** eol=lf
7+
8+
# VerifyTests
9+
*.verified.txt text eol=lf working-tree-encoding=UTF-8

‎.github/actions/build/action.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,5 @@ runs:
2020
shell: bash
2121
working-directory: templates
2222

23-
- run: dotnet build -c Release --warnAsError
23+
- run: dotnet build -c Release --warnAsError --maxcpucount
2424
shell: bash

‎.github/codeql-config.yml

-2
This file was deleted.

‎.github/workflows/ci.yml

+2-5
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,9 @@ jobs:
3131
shell: bash
3232
working-directory: templates
3333

34-
- run: dotnet test -c Release -f net8.0 --no-build --collect:"XPlat Code Coverage"
34+
- run: dotnet test -c Release -f net8.0 --no-build --collect:"XPlat Code Coverage" --consoleLoggerParameters:"Summary;Verbosity=Minimal"
3535

36-
- run: dotnet test -c Release -f net6.0 --no-build --collect:"XPlat Code Coverage"
36+
- run: dotnet test -c Release -f net6.0 --no-build --collect:"XPlat Code Coverage" --consoleLoggerParameters:"Summary;Verbosity=Minimal"
3737
if: matrix.os == 'ubuntu-latest'
3838

3939
- run: npm i -g @percy/cli
@@ -44,9 +44,6 @@ jobs:
4444
env:
4545
PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
4646

47-
- uses: codecov/codecov-action@v4
48-
if: matrix.os == 'ubuntu-latest'
49-
5047
- run: echo "DOTNET_DbgEnableMiniDump=1" >> $GITHUB_ENV
5148
if: matrix.os == 'ubuntu-latest'
5249

‎.github/workflows/codeql.yml

-34
This file was deleted.

‎.github/workflows/release.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,9 @@ jobs:
1616

1717
- name: dotnet publish
1818
run: |
19-
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
20-
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
21-
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
19+
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
20+
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
21+
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
2222
mkdir -p drop/bin
2323
2424
- run: zip -r ../../bin/docfx-win-x64-${GITHUB_REF_NAME}.zip .

‎Directory.Build.props

+8
Original file line numberDiff line numberDiff line change
@@ -59,4 +59,12 @@
5959
</PackageReference>
6060
</ItemGroup>
6161

62+
63+
<!-- Remove Node.js runtime dependencies that used by playwright -->
64+
<Target Name="RemoveNodeJsRuntimes" AfterTargets="CopyPlaywrightFilesToOutput">
65+
<ItemGroup>
66+
<Content Remove="@(Content)" Condition="$([System.String]::Copy('%(Content.PlaywrightFolder)').Contains('node\'))" />
67+
</ItemGroup>
68+
</Target>
69+
6270
</Project>

‎Directory.Packages.props

+65-65
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,65 @@
1-
<Project>
2-
<!-- See https://learn.microsoft.com/nuget/consume-packages/Central-Package-Management -->
3-
<PropertyGroup>
4-
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
5-
</PropertyGroup>
6-
<ItemGroup>
7-
<PackageVersion Include="HtmlAgilityPack" Version="1.11.61" />
8-
<PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
9-
<PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
10-
<PackageVersion Include="Jint" Version="3.1.3" />
11-
<PackageVersion Include="JsonSchema.Net" Version="7.0.4" />
12-
<PackageVersion Include="Markdig" Version="0.37.0" />
13-
<PackageVersion Include="Microsoft.Playwright" Version="1.44.0" />
14-
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
15-
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
16-
<PackageVersion Include="OneOf" Version="3.0.271" />
17-
<PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
18-
<PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240612-d2cae" />
19-
<PackageVersion Include="PlantUml.Net" Version="1.4.80" />
20-
<PackageVersion Include="PolySharp" Version="1.14.1" />
21-
<PackageVersion Include="Spectre.Console" Version="0.49.1" />
22-
<PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
23-
<PackageVersion Include="Stubble.Core" Version="1.10.8" />
24-
<PackageVersion Include="System.Collections.Immutable" Version="8.0.0" />
25-
<PackageVersion Include="System.Composition" Version="8.0.0" />
26-
<PackageVersion Include="YamlDotNet" Version="15.3.0" />
27-
</ItemGroup>
28-
29-
<ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
30-
<!-- "17.3.2" is the latest compatible version for .NET 6 -->
31-
<PackageVersion Include="Microsoft.Build" Version="[17.3.2]" />
32-
<PackageVersion Include="Microsoft.Build.Locator" Version="1.7.8" />
33-
<PackageVersion Include="Microsoft.CodeAnalysis" Version="[4.8.0]" />
34-
<PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="[4.8.0]" />
35-
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="[4.8.0]" />
36-
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="[4.8.0]" />
37-
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="[4.8.0]" />
38-
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="[4.8.0]" />
39-
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="[4.8.0]" />
40-
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="[4.8.0]" />
41-
</ItemGroup>
42-
43-
<ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
44-
<PackageVersion Include="Microsoft.CodeAnalysis" Version="4.10.0" />
45-
<PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.10.0" />
46-
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.10.0" />
47-
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.10.0" />
48-
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.10.0" />
49-
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.10.0" />
50-
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.10.0" />
51-
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.10.0" />
52-
</ItemGroup>
53-
54-
<ItemGroup>
55-
<!-- Test only -->
56-
<PackageVersion Include="coverlet.collector" Version="6.0.2" />
57-
<PackageVersion Include="FluentAssertions" Version="6.12.0" />
58-
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
59-
<PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
60-
<PackageVersion Include="Verify.DiffPlex" Version="2.3.0" />
61-
<PackageVersion Include="Verify.Xunit" Version="25.0.3" />
62-
<PackageVersion Include="xunit.runner.visualstudio" Version="2.8.1" />
63-
<PackageVersion Include="xunit" Version="2.8.1" />
64-
</ItemGroup>
65-
</Project>
1+
<Project>
2+
<!-- See https://learn.microsoft.com/nuget/consume-packages/Central-Package-Management -->
3+
<PropertyGroup>
4+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
5+
</PropertyGroup>
6+
<ItemGroup>
7+
<PackageVersion Include="HtmlAgilityPack" Version="1.11.61" />
8+
<PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
9+
<PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
10+
<PackageVersion Include="Jint" Version="3.1.4" />
11+
<PackageVersion Include="JsonSchema.Net" Version="7.1.2" />
12+
<PackageVersion Include="Markdig" Version="0.37.0" />
13+
<PackageVersion Include="Microsoft.Playwright" Version="1.45.0" />
14+
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
15+
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
16+
<PackageVersion Include="OneOf" Version="3.0.271" />
17+
<PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
18+
<PackageVersion Include="PdfPig" Version="0.1.9-alpha-20240702-65c64" />
19+
<PackageVersion Include="PlantUml.Net" Version="1.4.80" />
20+
<PackageVersion Include="PolySharp" Version="1.14.1" />
21+
<PackageVersion Include="Spectre.Console" Version="0.49.1" />
22+
<PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
23+
<PackageVersion Include="Stubble.Core" Version="1.10.8" />
24+
<PackageVersion Include="System.Collections.Immutable" Version="8.0.0" />
25+
<PackageVersion Include="System.Composition" Version="8.0.0" />
26+
<PackageVersion Include="YamlDotNet" Version="15.3.0" />
27+
</ItemGroup>
28+
29+
<ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
30+
<!-- "17.3.2" is the latest compatible version for .NET 6 -->
31+
<PackageVersion Include="Microsoft.Build" Version="[17.3.2]" />
32+
<PackageVersion Include="Microsoft.Build.Locator" Version="1.7.8" />
33+
<PackageVersion Include="Microsoft.CodeAnalysis" Version="[4.8.0]" />
34+
<PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="[4.8.0]" />
35+
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="[4.8.0]" />
36+
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="[4.8.0]" />
37+
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="[4.8.0]" />
38+
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="[4.8.0]" />
39+
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="[4.8.0]" />
40+
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="[4.8.0]" />
41+
</ItemGroup>
42+
43+
<ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
44+
<PackageVersion Include="Microsoft.CodeAnalysis" Version="4.10.0" />
45+
<PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.10.0" />
46+
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.10.0" />
47+
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.10.0" />
48+
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.10.0" />
49+
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.10.0" />
50+
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.10.0" />
51+
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.10.0" />
52+
</ItemGroup>
53+
54+
<ItemGroup>
55+
<!-- Test only -->
56+
<PackageVersion Include="coverlet.collector" Version="6.0.2" />
57+
<PackageVersion Include="FluentAssertions" Version="6.12.0" />
58+
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
59+
<PackageVersion Include="PublicApiGenerator" Version="11.1.0" />
60+
<PackageVersion Include="Verify.DiffPlex" Version="3.1.0" />
61+
<PackageVersion Include="Verify.Xunit" Version="25.3.0" />
62+
<PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
63+
<PackageVersion Include="xunit" Version="2.9.0" />
64+
</ItemGroup>
65+
</Project>

‎Dockerfile

+16-3
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,31 @@ FROM mcr.microsoft.com/dotnet/sdk:8.0-bookworm-slim
33
# Add dotnet tools to path.
44
ENV PATH="${PATH}:/root/.dotnet/tools"
55

6+
# Set target docfx version.
7+
ARG DOCFX_VERSION=2.77.0
8+
69
# Install DocFX as a dotnet tool.
7-
RUN dotnet tool update -g docfx && \
8-
docfx --version
10+
RUN dotnet tool install docfx -g --version ${DOCFX_VERSION} && \
11+
docfx --version && \
12+
rm -f /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/docfx.nupkg && \
13+
rm -f /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/docfx.${DOCFX_VERSION}.nupkg && \
14+
rm -rf /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net6.0
915

10-
# Install dependences for chromium PDF.
16+
# Install Node.js and dependences for chromium PDF.
1117
RUN apt-get update -qq && \
1218
apt-get install -y -qq --no-install-recommends \
19+
nodejs \
1320
libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
1421
libdbus-1-3 libxcb1 libxkbcommon0 libatspi2.0-0 libx11-6 libxcomposite1 libxdamage1 \
1522
libxext6 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2 && \
1623
rm -rf /var/lib/apt/lists/* /tmp/*
1724

25+
# Install Chromium.
26+
RUN PLAYWRIGHT_NODEJS_PATH="/usr/bin/node" && \
27+
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 && \
28+
pwsh -File /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/playwright.ps1 install chromium && \
29+
unlink /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/.playwright
30+
1831
WORKDIR /opt/prj
1932
VOLUME [ "/opt/prj" ]
2033

‎docs/docs/pdf.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Indicates whether to include background graphics when rendering the pdf.
8585

8686
### `pdfHeaderTemplate`
8787

88-
HTML template for the print header. Should be valid HTML markup with following HTML elements used to inject printing values into them:
88+
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:
8989

9090
- `<span class='pageNumber'></span>`: current page number.
9191
- `<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
9595

9696
### `pdfFooterTemplate`
9797

98-
HTML template for the print footer. Should use the same format as the [header template](#pdfheadertemplate). Uses the following default footer template if unspecified:
98+
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:
9999

100100
```html
101101
<div style="width: 100%; font-size: 12px;">

‎docs/reference/docfx-cli-reference/docfx-metadata.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -95,11 +95,19 @@ Run `docfx metadata --help` or `docfx -h` to get a list of all available options
9595
- `SeparatePages`
9696
- Place members in separate pages.
9797

98+
- **--useClrTypeNames**
99+
100+
Indicates whether the CLR type names or the language aliases must be used.
101+
102+
- not specified or `false`
103+
- The language aliases are used: `int`.
104+
- `true`
105+
- The CLR type names are used: `Int32`.
106+
98107
## Examples
99108

100109
- Generate YAML files with default config.
101110

102111
```pwsh
103112
docfx metadata
104113
```
105-

‎docs/reference/docfx-environment-variables-reference.md

+6-1
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,9 @@ This setting is intended to be used on offline environment.
2626

2727
## `DOCFX_PDF_TIMEOUT`
2828

29-
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.
29+
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.
30+
31+
## `PLAYWRIGHT_NODEJS_PATH`
32+
33+
Custom Node.js executable path that will be used by the `docfx pdf' command.
34+
By default, docfx automatically detect installed Node.js from `PATH`.

‎docs/tutorial/howto_add_a_customized_post_processor.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,7 @@ In this topic, we will show how to add a customized post-processor.
99

1010
* Create a new C# class library project in `Visual Studio`.
1111
* Add nuget packages:
12-
* [`System.Collections.Immutable`](https://www.nuget.org/packages/System.Collections.Immutable/1.3.1) with version 1.3.1
13-
* [`Microsoft.Composition`](https://www.nuget.org/packages/Microsoft.Composition/1.0.31) with version 1.0.31
12+
* [`System.Composition`](https://www.nuget.org/packages/System.Composition/8.0.0) with version 8.0.0
1413
* Add `Docfx.Plugins`
1514
If you are building DocFX from source code, add this reference to the project,
1615
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
5857

5958
## Step4: Build your project and copy the output dll files to:
6059

61-
* Global: the folder with name `Plugins` under the folder containing the Docfx executable
62-
* Non-global: the folder with name `Plugins` under a template folder, then run `DocFX build` command with parameter `-t {template}`.
60+
* Global: the folder that contains the Docfx executable.
61+
* Non-global: the folder with name `plugins` under a template folder, then run `DocFX build` command with parameter `-t {template}`.
6362

6463
*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.
6564

‎schemas/docfx.schema.json

+10
Original file line numberDiff line numberDiff line change
@@ -399,6 +399,7 @@
399399
"sitemap": {
400400
"type": "object",
401401
"description": "Specifies the options for the sitemap.xml file.",
402+
"additionalProperties": false,
402403
"properties": {
403404
"baseUrl": {
404405
"type": "string",
@@ -465,6 +466,7 @@
465466
"markdownEngineProperties": {
466467
"description": "Set the parameters for markdown engine, value should be a JSON string.",
467468
"type": "object",
469+
"additionalProperties": false,
468470
"properties": {
469471
"enableSourceInfo": {
470472
"type": "boolean",
@@ -520,6 +522,7 @@
520522
"plantUmlOptions": {
521523
"type": "object",
522524
"description": "PlantUml extension configuration parameters",
525+
"additionalProperties": false,
523526
"properties": {
524527
"javaPath": {
525528
"type": "string",
@@ -572,6 +575,7 @@
572575
"type": "array",
573576
"items": {
574577
"type": "object",
578+
"additionalProperties": false,
575579
"properties": {
576580
"src": {
577581
"$ref": "#/$defs/srcFileMapping"
@@ -688,6 +692,11 @@
688692
"type": "boolean",
689693
"default": false,
690694
"description": "When enabled, continues documentation generation in case of compilation errors."
695+
},
696+
"useClrTypeNames": {
697+
"type": "boolean",
698+
"default": false,
699+
"description": "When enabled, use CLR type names instead of language aliases."
691700
}
692701
}
693702
}
@@ -742,6 +751,7 @@
742751
"type": "array",
743752
"items": {
744753
"type": "object",
754+
"additionalProperties": false,
745755
"properties": {
746756
"content": {
747757
"$ref": "#/$defs/contentFileMapping"

0 commit comments

Comments
 (0)