diff options
| author | Leitwolf11 | 2026-10-03 13:04:35 +0300 |
|---|---|---|
| committer | Leitwolf11 | 2026-10-03 13:04:35 +0300 |
| commit | ca41877fafbac6cffc3e78db1d3306112e8acc60 (patch) | |
| tree | bd1f7e2e0e177396563da3bd9a9795c54bf65c15 | |
| parent | 8ba8d26ec4e6e900275fd5cd94e37a7aac701a1f (diff) | |
| download | progmaweb-ca41877fafbac6cffc3e78db1d3306112e8acc60.tar.gz | |
Add a DocFX documentation gate for the API
The backend workflow now builds the API reference with DocFX and treats
every warning as an error, so an unresolved reference or a broken link
fails the check.
- docs/api holds the DocFX project: it reads apps/api/Progmaweb.Api.csproj
and includes internal members, because the service is an application and
most of its types are internal.
- .config/dotnet-tools.json pins docfx 2.81.0, so CI and a local run use the
same version through `dotnet tool restore`.
- The workflow also runs when the DocFX project or the tool manifest change.
- `just api-docs` runs the same two commands locally.
- The generated site and metadata are ignored.
The gate does not require documentation comments: the API has none yet, and
DocFX does not report an undocumented member. Requiring them is a separate
change to the C# sources.
Verified locally with docfx 2.81.0 on the .NET 10 SDK: the build passes with
no warnings, and a broken link in the overview page makes it fail.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| -rw-r--r-- | .config/dotnet-tools.json | 11 | ||||
| -rw-r--r-- | .github/workflows/backend.yml | 9 | ||||
| -rw-r--r-- | .gitignore | 4 | ||||
| -rw-r--r-- | docs/api/docfx.json | 26 | ||||
| -rw-r--r-- | docs/api/index.md | 19 | ||||
| -rw-r--r-- | docs/api/toc.yml | 7 | ||||
| -rw-r--r-- | justfile | 4 |
7 files changed, 80 insertions, 0 deletions
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json new file mode 100644 index 0000000..e4d2756 --- /dev/null +++ b/.config/dotnet-tools.json @@ -0,0 +1,11 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "docfx": { + "version": "2.81.0", + "commands": ["docfx"], + "rollForward": false + } + } +} diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml index 173c5c6..a1f6320 100644 --- a/.github/workflows/backend.yml +++ b/.github/workflows/backend.yml @@ -11,6 +11,8 @@ on: - "apps/api-tests/**" - "Directory.Build.props" - "Progmaweb.slnx" + - "docs/api/**" + - ".config/dotnet-tools.json" - ".github/workflows/backend.yml" pull_request: paths: @@ -18,6 +20,8 @@ on: - "apps/api-tests/**" - "Directory.Build.props" - "Progmaweb.slnx" + - "docs/api/**" + - ".config/dotnet-tools.json" - ".github/workflows/backend.yml" workflow_dispatch: @@ -43,6 +47,11 @@ jobs: - run: dotnet build Progmaweb.slnx --configuration Release --no-restore - run: dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release --no-build --coverlet --coverlet-output-format cobertura + # Documentation gate: DocFX reads the API project and builds the + # reference; an unresolved reference or a broken link is an error. + - run: dotnet tool restore + - run: dotnet docfx docs/api/docfx.json --warningsAsErrors + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: progmaweb-backend-coverage @@ -18,3 +18,7 @@ obj/ .env .env.* !.env.example + +# DocFX output +docs/api/_site/ +docs/api/reference/ diff --git a/docs/api/docfx.json b/docs/api/docfx.json new file mode 100644 index 0000000..e10a9b0 --- /dev/null +++ b/docs/api/docfx.json @@ -0,0 +1,26 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../../apps/api", + "files": ["Progmaweb.Api.csproj"] + } + ], + "dest": "reference", + "includePrivateMembers": true + } + ], + "build": { + "content": [ + { + "files": ["index.md", "toc.yml", "reference/**/*.yml"] + } + ], + "dest": "_site", + "globalMetadata": { + "_appTitle": "Progmaweb API", + "_enableSearch": false + } + } +} diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..868fff1 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,19 @@ +<!-- +SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> +SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 +--> + +# Progmaweb API + +Reference documentation of the Progmaweb account service, generated by DocFX +from the XML documentation comments of `apps/api`. + +The service is an application, not a library, so most of its types are +internal. The reference includes them: it documents the code for the people +who maintain it. + +Build it from the repository root: + +```sh +docfx docs/api/docfx.json --warningsAsErrors +``` diff --git a/docs/api/toc.yml b/docs/api/toc.yml new file mode 100644 index 0000000..cf49dc1 --- /dev/null +++ b/docs/api/toc.yml @@ -0,0 +1,7 @@ +# SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> +# SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 + +- name: Overview + href: index.md +- name: Reference + href: reference/ @@ -19,3 +19,7 @@ api-test: dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release verify: web-check web-build api-build api-test + +api-docs: + dotnet tool restore + dotnet docfx docs/api/docfx.json --warningsAsErrors |