Merge pull request #179 from ottobolyos/chore/check-broken-links

ci: gate docs PRs on internal-link validity

Author: PatrickRitchie

.github/workflows/docs.yml

@@ -31,8 +31,8 @@ env:
   DOTNET_VERSION: '8.0.x'
 
 jobs:
-  build:
-    name: Build VitePress site
+  prepare-docs:
+    name: Prepare generated docs
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -68,6 +68,50 @@ jobs:
       - name: Verify reference pages match source (drift gate)
         run: bash docs/scripts/generate-reference.sh --check
 
+      # upload-artifact@v4 strips the longest common prefix from the path list
+      # (here: 'docs/'), so the artifact root contains 'api/' + 'reference/'
+      # rather than 'docs/api/' + 'docs/reference/'. The downstream
+      # download-artifact steps in the build and check-links jobs restore the
+      # 'docs/' prefix via 'path: docs'. This v4 behaviour differs from v3
+      # (which preserved the upload paths verbatim), so the two ends must stay
+      # in sync if either is touched.
+      - name: Upload generated docs
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: generated-docs
+          path: |
+            docs/api
+            docs/reference
+          if-no-files-found: error
+          retention-days: 1
+
+  build:
+    name: Build VitePress site
+    needs: prepare-docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Download generated docs
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: generated-docs
+          path: docs
+
       # Only required on push-to-master (deploy path). Computes the correct
       # base-path for the Pages site and writes it where later steps see it.
       - name: Configure GitHub Pages
@@ -88,6 +132,37 @@ jobs:
         with:
           path: docs/.vitepress/dist
 
+  check-links:
+    name: Check internal links
+    needs: prepare-docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Download generated docs
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: generated-docs
+          path: docs
+
+      - name: Check internal links
+        working-directory: docs
+        run: npm run check-links
+
   deploy:
     name: Deploy to GitHub Pages
     needs: build

docs/.docfx/docfx.json

@@ -16,7 +16,19 @@
             "libraries/MTConnect.NET-SysML/bin/Debug/net8.0/MTConnect.NET-SysML.dll",
             "libraries/MTConnect.NET-TLS/bin/Debug/net8.0/MTConnect.NET-TLS.dll",
             "libraries/MTConnect.NET-XML/bin/Debug/net8.0/MTConnect.NET-XML.dll",
-            "libraries/MTConnect.NET/bin/Debug/net8.0/MTConnect.NET.dll"
+            "libraries/MTConnect.NET/bin/Debug/net8.0/MTConnect.NET.dll",
+            "agent/MTConnect.NET-Agent/bin/Debug/net8.0/MTConnect.NET-Agent.dll",
+            "agent/MTConnect.NET-Applications-Agents/bin/Debug/net8.0/MTConnect.NET-Applications-Agents.dll",
+            "agent/Modules/MTConnect.NET-AgentModule-HttpServer/bin/Debug/net8.0/MTConnect.NET-AgentModule-HttpServer.dll",
+            "agent/Modules/MTConnect.NET-AgentModule-HttpAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-HttpAdapter.dll",
+            "agent/Modules/MTConnect.NET-AgentModule-MqttAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttAdapter.dll",
+            "agent/Modules/MTConnect.NET-AgentModule-MqttBroker/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttBroker.dll",
+            "agent/Modules/MTConnect.NET-AgentModule-MqttRelay/bin/Debug/net8.0/MTConnect.NET-AgentModule-MqttRelay.dll",
+            "agent/Modules/MTConnect.NET-AgentModule-ShdrAdapter/bin/Debug/net8.0/MTConnect.NET-AgentModule-ShdrAdapter.dll",
+            "adapter/MTConnect.NET-Adapter/bin/Debug/net8.0/MTConnect.NET-Adapter.dll",
+            "adapter/MTConnect.NET-Applications-Adapter/bin/Debug/net8.0/MTConnect.NET-Applications-Adapter.dll",
+            "adapter/Modules/MTConnect.NET-AdapterModule-MQTT/bin/Debug/net8.0/MTConnect.NET-AdapterModule-MQTT.dll",
+            "adapter/Modules/MTConnect.NET-AdapterModule-SHDR/bin/Debug/net8.0/MTConnect.NET-AdapterModule-SHDR.dll"
           ],
           "src": "../.."
         }

docs/.vitepress/config.ts

@@ -91,6 +91,9 @@ export default withMermaid(
               { text: 'Agent configuration', link: '/configure/agent-config' },
               { text: 'Adapter configuration', link: '/configure/adapter-config' },
               { text: 'Module configuration', link: '/configure/module-config' },
+              { text: 'Run', link: '/configure/run' },
+              { text: 'Connect a consumer', link: '/configure/consumer' },
+              { text: 'Operate', link: '/configure/operate' },
             ],
           },
           {

docs/README.md

@@ -53,7 +53,7 @@ Mermaid syntax is documented at <https://mermaid.js.org/intro/syntax-reference.h
 
 ## Authoring conventions
 
-- Internal links use site-relative paths (`/configure/agent`, not `../configure/agent.md`).
+- Internal links use site-relative paths (`/configure/agent-config`, not `../configure/agent-config.md`).
 - Code samples include the target language fence (` ```csharp `, ` ```bash `, ` ```yaml `).
 - External links use the full URL.
 - The site is configured with `cleanUrls: true`; pages are linked without the `.md` suffix.

docs/cli/adapter.md

@@ -169,10 +169,10 @@ To raise the console target to debug-level on a single run, use the `debug` comm
 
 ## See also
 
-- [Configure & Use → Configure an adapter](/configure/adapter) — annotated end-to-end `adapter.config.yaml` walkthrough plus data-source bring-up.
+- [Configure & Use → Configure an adapter](/configure/adapter-config) — annotated end-to-end `adapter.config.yaml` walkthrough plus data-source bring-up.
 - [Configure & Use → Run](/configure/run) — local-dev, Windows-service, and systemd-unit deployment.
 - [Modules](/modules/) — per-module configuration schemas referenced by the `modules:` list.
-- [API reference → `MTConnect.Applications.MTConnectAdapterApplication`](/api/) — the C# class that backs the CLI.
-- [API reference → `MTConnect.Configurations.AdapterApplicationConfiguration`](/api/) — the configuration POCO the YAML deserializes into.
-- [API reference → `MTConnect.Adapters.MTConnectAdapter`](/api/) — the inner adapter type that orchestrates `WriteObservations` / `WriteAssets` / `WriteDevices`.
+- [API reference → `MTConnect.Applications.MTConnectAdapterApplication`](/api/MTConnect.Applications.MTConnectAdapterApplication) — the C# class that backs the CLI.
+- [API reference → `MTConnect.Configurations.AdapterApplicationConfiguration`](/api/MTConnect.Configurations.AdapterApplicationConfiguration) — the configuration POCO the YAML deserializes into.
+- [API reference → `MTConnect.Adapters.MTConnectAdapter`](/api/MTConnect.Adapters.MTConnectAdapter) — the inner adapter type that orchestrates `WriteObservations` / `WriteAssets` / `WriteDevices`.
 - [Agent CLI](./agent) — the sibling agent host that consumes the adapter's output.

docs/cli/agent.md

@@ -135,11 +135,11 @@ Multiple instances of the same module are allowed — each entry produces a dist
 
 ### Processor list shape
 
-`processors` follows the same single-key-map-per-entry shape as `modules`. Each processor is a hook into the observation pipeline that runs between the adapter intake and the buffer write. The processor catalog lives under [API reference → MTConnect.Processors](/api/).
+`processors` follows the same single-key-map-per-entry shape as `modules`. Each processor is a hook into the observation pipeline that runs between the adapter intake and the buffer write. The processor catalog lives under [`MTConnect.Agents.MTConnectAgentProcessors`](/api/MTConnect.Agents.MTConnectAgentProcessors).
 
 ### Devices file
 
-The `devices` key points at one `Devices.xml` file or at a directory containing several. The schema is the MTConnect Devices envelope; each device's `<Components>` and `<DataItems>` graph drives what the agent exposes on `/probe`. The agent re-reads the device file when `monitorConfigurationFiles: true` is set. See [Configure & Use → Configure an agent](/configure/agent) for an annotated `Devices.xml` example.
+The `devices` key points at one `Devices.xml` file or at a directory containing several. The schema is the MTConnect Devices envelope; each device's `<Components>` and `<DataItems>` graph drives what the agent exposes on `/probe`. The agent re-reads the device file when `monitorConfigurationFiles: true` is set. See [Configure & Use → Configure an agent](/configure/agent-config) for an annotated `Devices.xml` example.
 
 ## NLog configuration
 
@@ -164,10 +164,10 @@ To raise the console target to `Debug` or `Trace` on a single run without editin
 
 ## See also
 
-- [Configure & Use → Configure an agent](/configure/agent) — annotated end-to-end `agent.config.yaml` walkthrough.
+- [Configure & Use → Configure an agent](/configure/agent-config) — annotated end-to-end `agent.config.yaml` walkthrough.
 - [Configure & Use → Run](/configure/run) — local-dev, Docker, Windows-service, and systemd-unit deployment.
 - [Modules](/modules/) — per-module configuration schemas referenced by the `modules:` list.
-- [API reference → `MTConnect.Applications.MTConnectAgentApplication`](/api/) — the C# class that backs the CLI.
-- [API reference → `MTConnect.Configurations.AgentApplicationConfiguration`](/api/) — the configuration POCO the YAML deserializes into.
-- [API reference → `MTConnect.Configurations.AgentConfiguration`](/api/) — the base class that holds the buffer / version / validation knobs.
+- [API reference → `MTConnect.Applications.MTConnectAgentApplication`](/api/MTConnect.Applications.MTConnectAgentApplication) — the C# class that backs the CLI.
+- [API reference → `MTConnect.Configurations.AgentApplicationConfiguration`](/api/MTConnect.Configurations.AgentApplicationConfiguration) — the configuration POCO the YAML deserializes into.
+- [API reference → `MTConnect.Configurations.AgentConfiguration`](/api/MTConnect.Configurations.AgentConfiguration) — the base class that holds the buffer / version / validation knobs.
 - [Adapter CLI](./adapter) — the sibling adapter host, run separately from the agent.

docs/cli/index.md

@@ -21,8 +21,8 @@ A PowerShell sibling lives alongside each shell script (`tools/dotnet.ps1`, `too
 
 ## Cross-references
 
-- [Configure & Use → Configure an agent](/configure/agent) — how to author the `agent.config.yaml` file the agent CLI reads.
-- [Configure & Use → Configure an adapter](/configure/adapter) — how to author the `adapter.config.yaml` file the adapter CLI reads.
+- [Configure & Use → Configure an agent](/configure/agent-config) — how to author the `agent.config.yaml` file the agent CLI reads.
+- [Configure & Use → Configure an adapter](/configure/adapter-config) — how to author the `adapter.config.yaml` file the adapter CLI reads.
 - [Configure & Use → Run](/configure/run) — how to invoke the agent / adapter in development, in Docker, or as a Windows service / systemd unit.
 - [Modules](/modules/) — the per-module configuration the agent CLI loads at startup.
 - [API reference](/api/) — the C# types that back each CLI (e.g. `MTConnectAgentApplication`, `MTConnectAdapterApplication`, `AgentApplicationConfiguration`, `AdapterApplicationConfiguration`).

docs/cli/sysml-import.md

@@ -97,9 +97,8 @@ A regeneration is considered clean when (a) the test suite is green at every pre
 
 - [Configure & Use → Run](/configure/run) — running the agent against the regenerated library to verify end-to-end behavior.
 - [Compliance](/compliance/) — the per-version compliance matrix that the regenerator advances.
-- [API reference → `MTConnect.SysML.MTConnectModel`](/api/) — the in-memory model the XMI parser produces and the renderers walk.
-- [API reference → `MTConnect.SysML.CSharp.CSharpTemplateRenderer`](/api/) — the C# renderer that produces `MTConnect.NET-Common`.
-- [API reference → `MTConnect.SysML.Xml.XmlTemplateRenderer`](/api/) — the XML renderer that produces `MTConnect.NET-XML`.
-- [API reference → `MTConnect.SysML.Json_cppagent.JsonCppAgentTemplateRenderer`](/api/) — the JSON v2 renderer that produces `MTConnect.NET-JSON-cppagent`.
+- [API reference → `MTConnect.SysML.MTConnectModel`](/api/MTConnect.SysML.MTConnectModel) — the in-memory model the XMI parser produces and the renderers walk.
+- [API reference → `MTConnect.SysML.ModelHelper`](/api/MTConnect.SysML.ModelHelper) — the helper surface the per-language renderers call into.
+- [API reference → `MTConnect.SysML` namespace](/api/MTConnect.SysML) — the SysML model + per-renderer entry points.
 - [`tools/test.sh`](./test-sh) — runs after a regeneration to verify the suite stays green.
 - [`tools/dotnet.sh`](./dotnet-sh) — wraps the `dotnet run` invocation if the regeneration is being done inside a containerized SDK.

docs/compliance/known-divergences.md

@@ -34,7 +34,7 @@ The published v2.6 SysML XMI file (`MTConnectSysMLModel_V2.6.xml`) is byte-ident
 
 For DataItems with `representation="DATA_SET"` or `representation="TABLE"`, the SysML XMI declares the `result` property's type as a single `DataSet` class shared between the two representations, while the XSD declares two distinct complex types (`DataSetType` and `TableType`) with non-overlapping element shapes.
 
-**Library posture**: follows the XSD's two-class shape — `DataSetEntry` and `TableEntry` are distinct classes ([`MTConnect.Observations.DataSetEntry`](/api/MTConnect.Observations/DataSetEntry), [`MTConnect.Observations.TableEntry`](/api/MTConnect.Observations/TableEntry)). The on-the-wire output is XSD-validated; consumers parsing the XML never see ambiguity.
+**Library posture**: follows the XSD's two-class shape — `DataSetEntry` and `TableEntry` are distinct classes ([`MTConnect.Observations.DataSetEntry`](/api/MTConnect.Observations.DataSetEntry), [`MTConnect.Observations.TableEntry`](/api/MTConnect.Observations.TableEntry)). The on-the-wire output is XSD-validated; consumers parsing the XML never see ambiguity.
 
 **Filed**: [Redmine #3893](https://projects.mtconnect.org/issues/3893) (SysML Model Related Issues).
 

docs/compliance/per-version-matrix.md

@@ -4,7 +4,7 @@
 
 ## Spec versions supported
 
-The library tracks every published MTConnect spec version. The version constants live in [`MTConnect.MTConnectVersions`](/api/MTConnect/MTConnectVersions), and `MTConnectVersions.Max` advertises the latest one the library can serialize for.
+The library tracks every published MTConnect spec version. The version constants live in [`MTConnect.MTConnectVersions`](/api/MTConnect.MTConnectVersions), and `MTConnectVersions.Max` advertises the latest one the library can serialize for.
 
 | MTConnect version | Released by MTConnect | Library constant | Streams XSD | Devices XSD | Assets XSD | Error XSD |
 |---|---|---|---|---|---|---|
@@ -32,7 +32,7 @@ Note: v1.9 was never released — the MTConnect Standard's version numbering jum
 
 ## Per-envelope semantics
 
-Each cell in the matrix above means: the agent can be asked to emit the named envelope at the named spec version, and the output validates against the matching `MTConnect<Envelope>_<version>.xsd` schema published by the standard body. The version-aware serializers ([`Device.Process`](/api/MTConnect.Devices/Device#Process), [`DataItem.Process`](/api/MTConnect.Devices/DataItem#Process), [`Composition.Process`](/api/MTConnect.Devices/Composition#Process), and the per-envelope JSON / XML codecs) prune properties, DataItems, Components, and Assets whose `MinimumVersion` is above the target version, and prune any whose `MaximumVersion` is below it.
+Each cell in the matrix above means: the agent can be asked to emit the named envelope at the named spec version, and the output validates against the matching `MTConnect<Envelope>_<version>.xsd` schema published by the standard body. The version-aware serializers ([`Device.Process`](/api/MTConnect.Devices.Device), [`DataItem.Process`](/api/MTConnect.Devices.DataItem), [`Composition.Process`](/api/MTConnect.Devices.Composition), and the per-envelope JSON / XML codecs) prune properties, DataItems, Components, and Assets whose `MinimumVersion` is above the target version, and prune any whose `MaximumVersion` is below it.
 
 ## Type introduction inventory
 
@@ -58,7 +58,7 @@ Every introduction is auditable through the generated `.g.cs` files under `libra
 
 ## Header fields per version
 
-The `Header` element gains attributes over time. The library populates them based on the target version; the [`MTConnectAgentInformation`](/api/MTConnect.Agents/MTConnectAgentInformation) class is the source.
+The `Header` element gains attributes over time. The library populates them based on the target version; the [`MTConnectAgentInformation`](/api/MTConnect.Agents.MTConnectAgentInformation) class is the source.
 
 | Attribute | Introduced at | Notes |
 |---|---|---|