From a2af1afa97805b5030768d13f7b6e67e48ecf33e Mon Sep 17 00:00:00 2001 From: Jan Friedrich Date: Sun, 11 Oct 2026 23:56:01 +0200 Subject: [PATCH 1/2] generated API reference with DocFX #337 - docfx config in src/site/docfx, output target/site/api - build-api-docs.ps1, warnings as errors, in build-release.ps1 and CI - header link in antora playbook - old versions regenerated by scripts/archived/build-old-api-docs.ps1 - shared helpers in scripts/Common.psm1 --- .config/dotnet-tools.json | 13 + .github/workflows/build.yaml | 8 + .gitignore | 4 + AGENTS.md | 15 +- antora-playbook.yaml | 3 + doc/BUILDING.md | 16 ++ doc/RELEASING.md | 3 +- rat.excludesFile | 1 + scripts/Common.psm1 | 64 +++++ scripts/FakeCommands.TestHelper.ps1 | 66 ++++- scripts/archived/build-old-api-docs.Tests.ps1 | 153 +++++++++++ scripts/archived/build-old-api-docs.ps1 | 247 ++++++++++++++++++ scripts/build-api-docs.Tests.ps1 | 87 ++++++ scripts/build-api-docs.ps1 | 52 ++++ scripts/build-release.Tests.ps1 | 16 +- scripts/build-release.ps1 | 44 +--- src/changelog/3.5.1/337-api-reference.xml | 11 + .../modules/ROOT/pages/development.adoc | 8 + .../modules/ROOT/pages/manual/index.adoc | 1 + src/site/docfx/docfx.json | 73 ++++++ src/site/docfx/index.md | 7 + src/site/docfx/logo.svg | 17 ++ src/site/docfx/manual.md | 3 + src/site/docfx/template/public/main.css | 24 ++ src/site/docfx/toc.yml | 23 ++ 25 files changed, 905 insertions(+), 54 deletions(-) create mode 100644 .config/dotnet-tools.json create mode 100644 scripts/Common.psm1 create mode 100644 scripts/archived/build-old-api-docs.Tests.ps1 create mode 100644 scripts/archived/build-old-api-docs.ps1 create mode 100644 scripts/build-api-docs.Tests.ps1 create mode 100644 scripts/build-api-docs.ps1 create mode 100644 src/changelog/3.5.1/337-api-reference.xml create mode 100644 src/site/docfx/docfx.json create mode 100644 src/site/docfx/index.md create mode 100644 src/site/docfx/logo.svg create mode 100644 src/site/docfx/manual.md create mode 100644 src/site/docfx/template/public/main.css create mode 100644 src/site/docfx/toc.yml diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json new file mode 100644 index 000000000..1490bfb3a --- /dev/null +++ b/.config/dotnet-tools.json @@ -0,0 +1,13 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "docfx": { + "version": "2.81.0", + "commands": [ + "docfx" + ], + "rollForward": false + } + } +} diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index dbf190268..4ba411e81 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -58,6 +58,14 @@ jobs: run: | dotnet test ./src/log4net.sln + # Recompiles both shipping projects through docfx with warnings as errors, so a broken doc + # comment or cref fails the pull request rather than the release build. The script itself + # is covered on all three runners by the Pester suite below; the real docfx run needs one. + - name: API reference + if: matrix.os == 'ubuntu-latest' + shell: pwsh + run: ./scripts/build-api-docs.ps1 + # Pester 5.9 ships on all three runner images, so nothing is installed here. - name: Release script tests shell: pwsh diff --git a/.gitignore b/.gitignore index 48e60e698..45f91a147 100644 --- a/.gitignore +++ b/.gitignore @@ -218,6 +218,10 @@ _Pvt_Extensions # Maven target dir created during site build target +# Metadata generated by scripts/build-api-docs.ps1 +/src/site/docfx/log4net/ +/src/site/docfx/log4net.Ext.Mail/ + # other files to ignore old-log4net.snk src/GeneratedAssemblyInfo.cs diff --git a/AGENTS.md b/AGENTS.md index b81cf63d7..a2ba9cc9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -256,15 +256,28 @@ The manual lives in `src/site/antora/modules/ROOT/pages/`. A new appender page n not one: the page itself, an `xref` line in `nav.adoc` (kept alphabetical), and the appender table in `manual/configuration/appenders.adoc`. +The API reference is DocFX output from the XML doc comments, built by `scripts/build-api-docs.ps1` +into `target/site/api` and in CI with warnings as errors, so an unresolved `cref` or a missing +public doc comment fails the PR. The configuration is in `src/site/docfx/`; the `log4net` and +`log4net.Ext.Mail` folders generated there are ignored. `log4net` is documented as `net462`, since +the `NET462_OR_GREATER` types exist only there. The Ext.Mail entry sets `ProduceReferenceAssembly`, +without which Roslyn cannot match its project reference to log4net and warns. + ## Release scripts +- **Before writing a helper function in a script, grep `scripts/` for its name and its idiom** + (`Push-Location`, `Remove-Item`, `Get-Date`). A function two scripts need lives in + `scripts/Common.psm1`, imported with `Import-Module $PSScriptRoot/Common.psm1 -Force`, not + copied into the second script. A module takes its preferences from the global scope, so the + module sets `$ErrorActionPreference` itself. - **Every file `build-release.ps1` writes gets LF on every platform.** `Set-Content` writes `[Environment]::NewLine`; use `-NoNewline` with the lines joined by `` `n ``. A CR is invisible in an editor, and `sha512sum` on macOS reads it as part of the file name. - **Each release ships the verifier built with it**, so never add backward compatibility to `verify-release.ps1` or `.sh`: a compatibility skip path is a hole, not a courtesy. - The scripts are tested with Pester through `scripts/FakeCommands.TestHelper.ps1`, which shadows - `dotnet`, `git`, `gpg`, `zip` and `mvnw` with shims on a prepended `PATH`, because Pester `Mock` + `dotnet`, `git`, `gpg`, `zip`, `mvnw` and `curl` with shims on a prepended `PATH` (`FAKE_FAIL` names a + command, or a command and its first argument such as `dotnet docfx`), because Pester `Mock` intercepts only functions and cmdlets. CI runs the suite on macOS, Ubuntu and Windows, so keep the helper's `$IsWindows` branch working and put byte-level assertions where all three see them. diff --git a/antora-playbook.yaml b/antora-playbook.yaml index c8951d3f7..b5afa7e40 100644 --- a/antora-playbook.yaml +++ b/antora-playbook.yaml @@ -115,6 +115,9 @@ ui: Apache log4net