docs: add VitePress documentation site

[ottobolyos]

Summary

This branch delivers four things: a VitePress documentation site for the repository, a build gate that treats missing XML documentation as an error across the shipped libraries, a SysML-importer extension plus regeneration so every generated file is fully documented, and a concepts + migration narrative that pairs with the v7 agent-validation work now on master.

Documentation site

A VitePress site rooted at the existing top-level docs/ directory, with Mermaid diagrams enabled for architecture, sequence, class-relationship, state-machine, and wire-flow diagrams. The site documents the full repository: every shipped library and module, every CLI tool, every wire format and codec, every configuration option, the public-surface API, and the project's MTConnect Standard compliance posture.

Top-level navigation:

• Compliance -- per-version compliance matrix, wire-format compliance, spec-source-vs-implementation cross-references, known divergences, compliance test harness.
• Configure & Use -- install, agent configuration, adapter configuration, module configuration, integrations (InfluxDB, MQTT broker / cloud / TLS).
• Concepts -- Devices, Components, Data Items, Observations, Assets, Relationships, and the agent validation events family.
• API reference -- auto-generated per-type pages with namespace cross-links.
• Wire formats -- XML, JSON v1, JSON-CPPAGENT (v2), JSON-CPPAGENT-MQTT, SHDR, with sample envelopes, codec class names, and wire-flow diagrams.
• Modules -- HTTP server, MQTT broker, MQTT relay, MQTT adapter, HTTP adapter, SHDR adapter, and the adapter-side SHDR / MQTT outputs.
• CLI -- Agent and Adapter CLI references plus the contributor tools/dotnet.sh, tools/test.sh, and SysML importer.
• Cookbook -- write an agent, write an adapter, write a module, configure the MQTT relay, write a JSON-MQTT consumer, migrate between versions.
• Migration notes -- per-version migration playbooks, starting with the v7 ValidationResult consolidation.
• Troubleshooting -- common error modes, XSD validation failures, schema-version mismatches, MQTT TLS handshake issues.

Auto-generated API reference

The API reference under docs/api/ is generated by docfx from the Debug net8.0 build of every shipped library DLL plus its XML doc file. The configuration lives at docs/.docfx/docfx.json; the regeneration script at docs/scripts/generate-api-ref.sh compiles each library with -p:GenerateDocumentationFile=true and then runs docfx metadata, producing a flat Namespace.Type.md layout that VitePress consumes directly.

The per-type pages are gitignored and regenerated on every build, so the repository does not carry a stale copy of the API surface. The section landing page docs/api/index.md is the only tracked file under docs/api/.

The legacy v1 MTConnect.Assets.Json.CuttingTools.JsonProcessFeedrate shadows the cppagent v2 JsonProcessFeedRate on a case-insensitive module path; the legacy type is excluded via docs/.docfx/filter.yml so the module resolver does not collide on the case-variant pair. The cppagent v2 type stays in the reference.

Documentation gate

libraries/Directory.Build.props treats CS1591 (missing XML documentation comment) as a build error for the production libraries, so the API reference cannot regress to undocumented members. Every hand-authored and generated public, internal, and private type and member carries a substantive doc comment describing its contract.

SysML importer and regeneration

The SysML importer in MTConnect.NET-SysML is extended so the CompositionState and Direction event subtype value vocabularies (one enumeration per subtype) and the shared CuttingTool Measurement base are materialized as documented generated output instead of stale orphan files. The MTConnect.NET-Common library is regenerated from the mtconnect/mtconnect_sysml_model v2.7 tag; regeneration is deterministic, and stale v2.3 generator output superseded by the v2.7 equivalents has been removed.

Concepts: agent validation events

docs/concepts/agent-validation-events.md documents the full Invalid*Added family on MTConnectAgent from both the consumer and the contributor perspective: why the agent emits events instead of throwing, how each event maps to a delegate, the uniform handler signatures, the InputValidationLevel knob that gates everything, the per-failure-category ValidationResult.Code values, and the naming convention plus call-site pattern for adding a new family member. The page covers all six current entries (InvalidDeviceAdded, InvalidComponentAdded, InvalidCompositionAdded, InvalidDataItemAdded, InvalidObservationAdded, InvalidAssetAdded), including the pre-flight ValidateDevice(IDevice) helper that exposes the same check AddDevice runs internally.

Migration note: v7 ValidationResult consolidation

docs/migration/v7-validation-result.md is the migration playbook for the v7 collapse of three pre-v7 per-domain validation result structs (MTConnect.Assets.AssetValidationResult, MTConnect.Devices.DataItems.ValidationResult, MTConnect.Observations.ObservationValidationResult) into one universal MTConnect.ValidationResult with an added machine-readable Code property. Covers the type-replacement table, the Valid() / Invalid(code, message) factory shorthand, and before/after code samples for both the handler side (agent subscribers) and the Asset author side (Asset.IsValid overrides). Reachable via a new /migration/ sidebar group, which future migration notes can join.

CI

.github/workflows/docs.yml runs on every push and pull request to master. Each run sets up .NET 8.0 and Node 20, installs docfx, runs docs/scripts/generate-api-ref.sh, then npm run build inside docs/. On push to master the built site is uploaded as a Pages artifact and the deploy job publishes it to GitHub Pages. Action versions are SHA-pinned with tag aliases in trailing comments.

docs/package.json lives inside docs/; a !docs/package.json allow-list entry was added to .gitignore because the repository's blanket package.json ignore targets the legacy gulp-era build artefacts.

[PatrickRitchie]

It looks like the package.json file may be missing. Possibly filtered out of the git?

[ottobolyos]

One thing to flag before this merges, since it needs a decision only you can make.

The Docs site workflow (.github/workflows/docs.yml) has two jobs: Build VitePress site and Deploy to GitHub Pages. On a pull request the deploy job is intentionally skipped — it's gated if: github.event_name == 'push' && github.ref == 'refs/heads/master', so PRs build the site only (which is why you see Deploy to GitHub Pages showing as skipped on this PR), and a doc-breaking change still surfaces in the build job. That part is by design.

The decision is what should happen once this lands. On the push-to-master that the merge produces, the deploy job's condition becomes true and actions/deploy-pages will attempt to publish the built site. That step only succeeds if the repository has GitHub Pages configured with GitHub Actions as the source (Settings → Pages → Build and deployment → Source). If Pages isn't enabled, the workflow run on master will go red on the deploy step even though the site itself built cleanly.

Worth being precise about what this needs, since it's a common assumption: there's no secret to add for this path. The workflow uses the GitHub-Pages-native actions (configure-pages / upload-pages-artifact / deploy-pages), which authenticate via the workflow's own id-token: write OIDC token plus the built-in GITHUB_TOKEN — both already declared on the deploy job. So no API key, PAT, or deploy key is involved. The single prerequisite is the repository setting above (enabling it also provisions the github-pages environment the job targets). A secret would only come into play if you wanted to publish somewhere other than GitHub Pages (Netlify, Vercel, an internal host, etc.), which would be a different action and a different conversation.

So, a question and a couple of options:

• Do you want the docs published to GitHub Pages? If yes, the only thing needed is enabling Pages with the GitHub Actions source before (or right at) merge — the workflow already requests the pages: write + id-token: write permissions the deploy needs, and the artifact upload is wired. The site would land at the repository's Pages URL; if you'd want it under a custom domain or a non-default base path, that's a small docs/.vitepress/config change I can fold in here.
• Not yet / not via Pages? I can make the deploy job dormant so the merge can't produce a red master run — either drop the deploy job entirely (build-only, which still gives the PR-time doc-break gate), or gate it behind a repository variable (e.g. if: vars.DEPLOY_DOCS == 'true') so it stays inert until you flip the switch. Either is a one-commit change in this PR.

Happy to make whichever you prefer here so the merge is clean. If you'd rather sort the Pages setup separately and merge as-is, that works too — just let me know and I'll gate the deploy job so master stays green in the meantime.

[ottobolyos]

A separate design point on the generated reference pages, since this PR sets the policy and I'd rather raise it than let it set a precedent silently.

The branch treats the two generated doc trees differently: the docfx API pages under docs/api/ are gitignored and regenerated on every build (so the repo never carries a stale copy of the API surface), while the five Roslyn-generated pages under docs/reference/ (http-api, configuration, environment-variables, cli, index) are committed and protected by a build-time drift gate (generate-reference.sh --check) that fails CI if a source change wasn't reflected in a regenerated page.

On reflection I think docs/reference/ would be better off following the same gitignore-and-generate-at-build policy as docs/api/. The reasoning: those pages are derived from the C# itself — XML doc comments, the configuration classes, the HTTP route handlers, the MTCONNECT_* env-var lookups — which change continually. So there's a standing risk that someone edits the code, forgets to regenerate, and the committed pages drift out of date. The drift gate mitigates that, but it's really a band-aid: it turns "silently stale docs" into "a red check that forces a regen commit". Generating at build removes the failure mode entirely — there's nothing committed to go stale, and the cross-OS determinism issue that reddened the earlier Windows run (a CRLF trailing-\r divergence) can't recur, because there's no committed copy to diverge from.

The trade-off is real but modest: you'd lose the PR-diff visibility of a generated page changing, and the pages would no longer be browsable as raw files on GitHub — only on the built site. The source change that caused them is still reviewable.

My lean is to switch docs/reference/ to build-time generation, but it's your call, and either way I'd do it as a small follow-up rather than expanding this PR — so this one can merge on its current footing. If you'd rather keep the committed-and-gated approach, that's perfectly defensible too.

(The same question doesn't apply to the SysML-generated *.g.cs: those derive from the pinned external SysML model rather than from hand-written code, so they only change on a deliberate spec-version bump — committing them is the right call, with a regen drift-check as the natural safety net if one's wanted.)

[PatrickRitchie]

After merging into the master branch, the action completed successfully but it looks like some of the links are broken and the css doesn't load. Likely an issue with a base path or something? I'm not sure how GitHub Pages handles paths and relative links.

https://trakhound.github.io/MTConnect.NET

Let me know if there is something I need to configure on my end.

[ottobolyos]

I’ll look into this. I’ll fix all broken links and add a check for broken internal links (i.e. checking links referencing files/headings within the docs, not links referencing websites/URLs on the Internet).

[ottobolyos]

The is actually less about broken links (which there are too) and more about deployment to a /MTConnect.NET subpath, while VitePress config presumes deployment to /.

I’ll create separate PRs to fix the issues: 1.[#179] fix the broken links and prevent them; 2. [#180] add an env var so that we can build the docs to any URL path (e.g. we will use DOCS_BASE=/MTConnect.NET/ in the CI; it would still default to /).

I’ll prioritise #180 so that the deployed docs work as expected.

[ottobolyos]

@PatrickRitchie, both halves of that report are covered by open PRs. Proposed merge order:

1. feat(docs): expand API reference to every committed project #182,
2. feat(http): expose probe device model via Devices accessor #185,
3. feat(docs): apply maintainer house style to the VitePress docs site #186.