Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorLeitwolf112026-10-03 13:04:35 +0300
committerLeitwolf112026-10-03 13:04:35 +0300
commitca41877fafbac6cffc3e78db1d3306112e8acc60 (patch)
treebd1f7e2e0e177396563da3bd9a9795c54bf65c15 /docs
parent8ba8d26ec4e6e900275fd5cd94e37a7aac701a1f (diff)
downloadprogmaweb-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>
Diffstat (limited to 'docs')
-rw-r--r--docs/api/docfx.json26
-rw-r--r--docs/api/index.md19
-rw-r--r--docs/api/toc.yml7
3 files changed, 52 insertions, 0 deletions
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/