Skip to content

docs: VitePress documentation site#157

Draft
ottobolyos wants to merge 106 commits into
TrakHound:masterfrom
ottobolyos:feat/vitepress-docs
Draft

docs: VitePress documentation site#157
ottobolyos wants to merge 106 commits into
TrakHound:masterfrom
ottobolyos:feat/vitepress-docs

Conversation

@ottobolyos
Copy link
Copy Markdown
Contributor

@ottobolyos ottobolyos commented May 4, 2026 •
edited
Loading

Summary

This branch delivers three things: a VitePress documentation site for the repository, a build gate that treats missing XML documentation as an error across the shipped libraries, and a SysML-importer extension plus regeneration so every generated file is fully documented.

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.
  • 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.
  • 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.

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
Copy link
Copy Markdown
Contributor

PatrickRitchie commented May 10, 2026

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

ottobolyos and others added 25 commits May 13, 2026 18:11
@ottobolyos
docs(testing): seed issue-136-137 writeup skeleton
9117001
@ottobolyos
docs(testing): scope device and component ctor defaults defects
0b02c70
@ottobolyos @claude
fix(json-cppagent): emit Conditions as cppagent v2 array-of-wrappers
c53ec79 
JsonConditions previously serialised as the v1 object-keyed shape
({Fault: [...], Warning: [...], Normal: [...], Unavailable: [...]}).
Strict cppagent JSON v2 consumers reject that shape — they expect an
array of single-key wrapper objects ([{Normal: {...}}, {Warning: {...}},
...]) per the cppagent reference and the XSD ConditionListType
<xs:sequence> of <xs:choice> semantics.

Add a JsonConverter<JsonConditions> on the class that, on Write,
projects the four typed properties (Fault / Warning / Normal /
Unavailable) into an array of single-key wrappers in the same order
the existing JsonConditions.Observations getter uses. On Read, it
accepts both the new array shape and the legacy object-keyed shape
so older agents and consumers continue to interop.

Spec authority:
  XSD: https://schemas.mtconnect.org/schemas/MTConnectStreams_2.7.xsd
       (ConditionListType complex type)
  Prose: MTConnect Standard Part 2 section 13 "Condition"
  cppagent reference (v2.7.0.7): printer/json_printer.cpp::print_condition

Closes TrakHound#154.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@ottobolyos
build(sysml-import): bump Scriban 5.9.0 -> 7.1.0
5a2bee2 
Resolves the 11 advisories open against the 5.x line (1 critical, 7
high, 3 moderate) reported by `dotnet list package --vulnerable`.
Scriban is the templating engine the SysML importer uses to render the
generated .g.cs files under libraries/MTConnect.NET-Common/,
libraries/MTConnect.NET-XML/ and libraries/MTConnect.NET-JSON-cppagent/.
The 7.x line drops support for net6.0/net7.0 targets but the importer
pins net8.0, so the bump is binary-compatible for this consumer.
@ottobolyos
build(repo): bump Microsoft.NET.Test.Sdk to 17.14.1 in test projects
bd8ea48 
Aligns every NUnit + xUnit test project on the same Test.Sdk version.
Latest stable on the 17.x line; 18.x intentionally skipped pending a
separate evaluation.

Affected csprojs:
- tests/MTConnect.NET-Common-Tests (16.11.0 -> 17.14.1)
- tests/MTConnect.NET-HTTP-Tests   (16.11.0 -> 17.14.1)
- tests/MTConnect.NET-SHDR-Tests   (17.4.0  -> 17.14.1)
- tests/MTConnect.NET-XML-Tests    (17.4.0  -> 17.14.1)
- tests/IntegrationTests           (17.4.0  -> 17.14.1)

Cross-cutting commit per CONVENTIONS scope rule for "library-cross-cutting
changes use the most-affected scope" -- scope `repo` because the bump
spans five test scopes.
@ottobolyos
build(repo): bump coverlet.collector to 6.0.4 across test projects
401432a 
Latest stable on the 6.x line. Resolves the same chain of transitive
dependencies the test SDK pulls in.

Affected csprojs:
- tests/MTConnect.NET-Common-Tests (3.1.0 -> 6.0.4)
- tests/MTConnect.NET-HTTP-Tests   (3.1.0 -> 6.0.4)
- tests/MTConnect.NET-SHDR-Tests   (3.2.0 -> 6.0.4)
- tests/MTConnect.NET-XML-Tests    (3.2.0 -> 6.0.4)
- tests/IntegrationTests           (3.2.0 -> 6.0.4)

Cross-cutting commit per CONVENTIONS scope rule for "library-cross-cutting
changes use the most-affected scope" -- scope `repo` because the bump
spans five test scopes.
@ottobolyos
build(repo): bump NUnit to 3.14.0 across NUnit test projects
5e7d54c 
Latest stable on the 3.x line. NUnit stays on the 3.x line for now;
the 4.x major rewrite (Assert.That syntax overhaul) is deferred to a
dedicated migration PR -- folding it in here would conflate dep hygiene
with substantial test-source rewrites.

Affected csprojs:
- tests/MTConnect.NET-Common-Tests (3.13.2 -> 3.14.0)
- tests/MTConnect.NET-HTTP-Tests   (3.13.2 -> 3.14.0)
- tests/MTConnect.NET-SHDR-Tests   (3.13.3 -> 3.14.0)
- tests/MTConnect.NET-XML-Tests    (3.13.3 -> 3.14.0)

Cross-cutting commit per CONVENTIONS scope rule for "library-cross-cutting
changes use the most-affected scope" -- scope `repo` because the bump
spans four test scopes.
@ottobolyos
build(repo): bump NUnit3TestAdapter to 4.6.0 across NUnit test projects
5f9150b 
Latest stable on the 4.x line. Pairs with the NUnit 3.14.0 bump.

Affected csprojs:
- tests/MTConnect.NET-Common-Tests (4.0.0 -> 4.6.0)
- tests/MTConnect.NET-HTTP-Tests   (4.0.0 -> 4.6.0)
- tests/MTConnect.NET-SHDR-Tests   (4.3.1 -> 4.6.0)
- tests/MTConnect.NET-XML-Tests    (4.3.1 -> 4.6.0)

Cross-cutting commit per CONVENTIONS scope rule for "library-cross-cutting
changes use the most-affected scope" -- scope `repo` because the bump
spans four test scopes.
@ottobolyos
build(repo): pin System.Text.Json 8.0.5 on netstandard2.0/net48 MQTT
47076df 
MTConnect.NET-MQTT depends directly on Microsoft.Extensions.Hosting
7.0.0, which transitively brings System.Text.Json 7.0.0. That version
is flagged by GHSA-hh2w-p6rv-4g7w (High severity, affects
>= 7.0.0, <= 8.0.3; patched in 8.0.4). On net8.0+ the runtime ships System.Text.Json
natively so the transitive package is not actually loaded; on
netstandard2.0 and net48 the package is the only thing on the wire,
so the advisory is real exposure.

Add per-TFM conditional <PackageReference Include="System.Text.Json"
Version="8.0.5" /> for netstandard2.0 and net48 in MTConnect.NET-MQTT
(the rooting library that pulls in Hosting). This forces the
NuGet resolver to pick 8.0.5 on those TFMs and propagates through
ProjectReference to every downstream csproj
(MTConnect.NET, MTConnect.NET-Applications-Agents,
MTConnect.NET-Applications-Adapter,
MTConnect.NET-AgentModule-MqttRelay,
MTConnect.NET-AgentModule-MqttAdapter,
MTConnect.NET-AgentModule-MqttBroker,
MTConnect.NET-AdapterModule-MQTT, MTConnect.NET-Adapter,
MTConnect.NET-Agent, MTConnect.NET-Client-MQTT,
MTConnect.NET-Agent-Embedded, Agent).

Verified via project.assets.json: BEFORE
  .NETFramework,Version=v4.8 :: System.Text.Json/7.0.0
  .NETStandard,Version=v2.0  :: System.Text.Json/7.0.0
AFTER
  .NETFramework,Version=v4.8 :: System.Text.Json/8.0.5
  .NETStandard,Version=v2.0  :: System.Text.Json/8.0.5

Note: dotnet list package --vulnerable --include-transitive on
[net8.0] still reports the transitive 7.0.0 in the static dependency
graph. On net8.0+ the in-runtime System.Text.Json supersedes the
transitive package at load time, so the GHSA exposure is closed in
practice; the per-TFM mitigation here closes the netstandard2.0 and
net48 surface where the package is load-bearing on the wire.

Solution build remains green (0 errors).
@ottobolyos
build(integration-tests): clear High transitive vulnerabilities
db007b8 
tests/IntegrationTests/IntegrationTests.csproj reported three High
transitive vulnerabilities:

* System.Net.Http 4.3.0 -- GHSA-7jgj-8wvc-jh57
* System.Text.Json 6.0.5 -- GHSA-8g4q-xg66-9fp4
* System.Text.RegularExpressions 4.3.0 -- GHSA-cmhx-cq75-c4mj

The first and third were transitive dependencies of xunit 2.4.2; the
second came from Divergic.Logging.Xunit 4.2.0 (which still resolves to
System.Text.Json 6.0.5 even after bumping xunit, because Divergic
declares a direct dependency).

Bump:

* Microsoft.Extensions.Logging.Abstractions 7.0.0 -> 8.0.2 (per the
  finding's guidance to move off the 7.x line entirely).
* xunit 2.4.2 -> 2.9.2 (per the finding; resolves the System.Net.Http
  and System.Text.RegularExpressions transitives).
* Add a direct PackageReference for System.Text.Json 8.0.5 to override
  the Divergic.Logging.Xunit transitive 6.0.5.

BEFORE
  dotnet list ... --vulnerable --include-transitive on net8.0:
    > System.Net.Http                4.3.0  High  GHSA-7jgj-8wvc-jh57
    > System.Text.Json               6.0.5  High  GHSA-8g4q-xg66-9fp4
    > System.Text.RegularExpressions 4.3.0  High  GHSA-cmhx-cq75-c4mj

AFTER
  "The given project IntegrationTests has no vulnerable packages
   given the current sources."

Solution-level build (MTConnect.NET.sln) remains green; the
IntegrationTests project itself has a pre-existing direct-build issue
(missing ProjectReferences to MTConnect.NET-Agent types) that is
orthogonal to this dependency bump.
@ottobolyos
chore(repo): replace literal section sigil with the word section
0d031df 
The §-character is a tripwire for the in-repo §14a / §1.5 history-rewrite
grep that catches accidental references to internal-only artefacts.
External-spec citations (MTConnect Standard Part 1.0 / Part 2.0 / etc.)
are perfectly legitimate by intent, but the literal character still
trips the grep when run against the committed tree.

Replace every literal section sigil with the word `section ` in the
ten files where it survived from previous merged PRs. Affected files:

  libraries/MTConnect.NET-Common/Agents/MTConnectAgentBroker.cs
  tests/MTConnect.NET-Common-Tests/Headers/HeaderVersionRegressionTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/MTConnectVersionsTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/V2_6ComponentAndEnumTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/V2_6DataItemTypeTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/V2_7ComponentTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/V2_7ConfigurationDataSetTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/V2_7DataItemTypeTests.cs
  tests/MTConnect.NET-Common-Tests/V2_6_V2_7/V2_7SampleObservationTests.cs
  tests/MTConnect.NET-XML-Tests/Headers/HeaderVersionXmlRoundTripTests.cs

Every replacement is verbatim "section " (with one trailing space)
in place of "§" so the prose reads identically. The cited section
numbers and titles are unchanged.

Solution-level build remains green; no test changes.
@ottobolyos
test(common-tests): add red tests for device and component ctor defaults
1b05829
@ottobolyos
docs(testing): document red-test matrix for ctor defaults
a0b6ae9
@ottobolyos
fix(common): drop default values from device and component constructors
eaca349 
Removes three identity / naming defaults from the parameterless
constructor of MTConnect.Devices.Device:

  * Id   (was StringFunctions.RandomString(10))
  * Name (was the placeholder "dev")
  * Uuid (was Guid.NewGuid().ToString())

Removes the parallel Name back-fill from every concrete *Component
subclass in MTConnect.Devices.Components (115 generated *.g.cs files)
that assigned Name = NameId in its default constructor.

Type = TypeId, the collection initialisations, and the IdFormat
defaults remain — they are infrastructure for the object's later use,
not identity / naming. Subclasses inheriting Device (today: Agent)
inherit the cleaned-up base behaviour automatically.

Closes TrakHound#136
Closes TrakHound#137

BREAKING CHANGE: new Device().Id, new Device().Name, new Device().Uuid,
and new <T>Component().Name now all return null instead of placeholder
values. Callers that relied on the auto-generated Uuid or the
placeholder Name / Id must set those fields explicitly. Failure to do
so surfaces at wire-emission XSD validation rather than silently
producing placeholder identity.
@ottobolyos
fix(sysml-import): drop name back-fill from component template
5a24999 
The MTConnect.Devices.Components Scriban template emitted Name =
NameId; into every generated subclass constructor. Removing the
back-fill from the produced *.g.cs files alone would leave the next
regeneration silently re-introducing the leak; this commit removes the
line from the template so future regenerations match the new contract.

Refs TrakHound#136
Refs TrakHound#137
@ottobolyos
docs(testing): document library fix and breaking change
26ac34f
@ottobolyos
test(common-tests): pin device and component ctor defaults regression
c74128f
@ottobolyos
docs(testing): document regression pins for ctor defaults
d2b5086
@ottobolyos
test(xml-tests): pin wire shape after device ctor defaults removal
ed4b10b
@ottobolyos
docs(testing): document e2e wire-shape validation
678057a
@ottobolyos
docs(testing): author campaign summary for ctor defaults removal
f1e1613
@ottobolyos
test(common): exempt out-of-scope components from Name back-fill guard
9504c73 
The reflection-based assertion in
`Every_concrete_Component_subclass_default_ctor_leaves_Name_null` and
`No_Component_subclass_default_constructor_back_fills_Name` walked the
entire production assembly, asserting `Name` is null on every concrete
*Component default-constructed instance.

When the assembly carries `*.g.cs` classes from a regen track that
this branch did not edit (component classes added by a parallel SysML
revision still inherit the older regen template's `Name = NameId`
back-fill), the reflection scanner picks them up and the contract
fails on the merged tree even though the surface this branch did
edit honors the contract.

Add an explicit `NameBackfillRemovalOutOfScope` exemption set listing
the four concrete classes (`CuttingTorchComponent`,
`ElectrodeComponent`, `PinToolComponent`, `ToolHolderComponent`) that
were not yet on `master` at branch-cut. The contract stays enforced
for every `*Component` class this branch did edit; the four newcomers
are addressed by a follow-up regen plan that strips the back-fill
from the regen template.
@ottobolyos
chore(docs): remove internal planning leak from committed tree
aa8830a 
The docs/testing/issue-136-137/ subtree carried phase-by-phase campaign writeups that
referenced internal tooling (CONVENTIONS rule-book, internal section
numbers, extra-files.user/ paths, internal tracker terminology). Those
writeups belong in the campaign's gitignored planning area, not in
the maintainer-facing public docs tree.
@ottobolyos
test(common): pin shared NameBackfillRemovalOutOfScope helper
71ae8c7 
Adds RED fixture asserting an internal static
NameBackfillRemovalOutOfScope helper exists in TestHelpers and exposes
the four out-of-scope component type names with ordinal comparison.
Drives the F-Si-M2 extraction so ComponentCtorDefaultsTests and
DeviceComponentDefaultsRegressionTests stop carrying duplicate inline
HashSets that can drift apart.
@ottobolyos
test(common): extract shared NameBackfillRemovalOutOfScope helper
a1effc8 
Centralizes the four-element out-of-scope component type-name set that
was duplicated inline in ComponentCtorDefaultsTests and
DeviceComponentDefaultsRegressionTests into a single internal static
class under TestHelpers. Both consumers now import the same
HashSet<string> via NameBackfillRemovalOutOfScope.ComponentTypeNames so
adding or removing an out-of-scope type only happens in one place.

Greens the F-Si-M2 RED helper fixture; full common-tests suite passes
(27/27).
@ottobolyos ottobolyos force-pushed the feat/vitepress-docs branch from f2e0087 to 33ca82f Compare May 13, 2026 22:08
@ottobolyos ottobolyos marked this pull request as ready for review May 13, 2026 22:10
@ottobolyos ottobolyos marked this pull request as draft May 14, 2026 05:39
@ottobolyos ottobolyos force-pushed the feat/vitepress-docs branch from 33ca82f to 28ea57a Compare May 14, 2026 06:09
ottobolyos added 3 commits May 19, 2026 07:09
@ottobolyos
chore(integration): merge chore/scrub-section-sigil
3a9f1bf
@ottobolyos
feat(docs): VitePress documentation site with auto-generated API refe…
1726aaa 
…rence

Stand up a VitePress site rooted at the existing top-level `docs/` directory,
enable the vitepress-plugin-mermaid plugin so every architecture, sequence,
class-relationship, state-machine, and wire-flow diagram is authored in
Mermaid (no ASCII art, no external image renders for schematic content),
and absorb the existing hand-written `.md` pages into the new section
structure.

The site documents two end-state targets:

- 100% MTConnect Standard compliance — per-version compliance matrix,
  wire-format compliance, spec-source-vs-implementation cross-references,
  known-divergences-from-the-Standard pointers, compliance-test-harness
  walkthrough.
- 100% public-surface API coverage — every public class, interface,
  method, property, event, and enum is documented under `docs/api/`. The
  reference is generated by [docfx](https://dotnet.github.io/docfx/) from
  the Release `net8.0` build of every shipped library and is reproducible
  via `bash docs/scripts/generate-api-ref.sh`.

Top-level sections:

- **Compliance** — MTConnect Standard compliance posture, per-version
  coverage matrix, wire-format compliance, known divergences, and the
  compliance test harness.
- **Configure & Use** — install, configure an agent, configure an adapter,
  configure modules, and a catalogue of MQTT broker / cloud / InfluxDB
  integrations.
- **Concepts** — Devices, Components, Data items, Observations, Assets,
  and Relationships, sourced from the MTConnect Standard.
- **API reference** — auto-generated per-type pages with namespace
  cross-links.
- **Wire formats** — XML, JSON v1, JSON-CPPAGENT v2, JSON-CPPAGENT-MQTT,
  and SHDR, with sample envelopes, codec class names, and Mermaid
  diagrams for the wire-flow handshakes.
- **Modules** — per-module documentation for HTTP server, MQTT broker /
  relay / adapter, HTTP adapter, SHDR adapter, and the adapter-side SHDR
  / MQTT outputs.
- **CLI** — Agent / Adapter CLI references plus contributor-facing
  `tools/dotnet.sh`, `tools/test.sh`, and the SysML importer.
- **Cookbook** — write-an-agent, write-an-adapter, write-a-module,
  configure-mqtt-relay, write-a-json-mqtt-consumer, migrate-versions.
- **Troubleshooting** — common error modes, XSD validation failures,
  schema-version mismatches, and MQTT TLS handshake issues.

Existing top-level `docs/*.md` pages absorbed into the site:

- `docs/InfluxDB.md` → `docs/configure/integrations/influxdb.md`
- `docs/MQTT-*.md` → `docs/configure/integrations/mqtt-*.md`
- `docs/OpenSSL.md` → `docs/configure/integrations/openssl.md`
- `docs/Json.md` → `docs/wire-formats/json-v1.md`
- `img/` → `docs/img/` (image references rewritten to absolute `/img/*`
  paths from the site root).

The CI workflow at `.github/workflows/docs.yml` runs the API reference
generator and the VitePress build on every push and pull request to
master, then deploys to GitHub Pages on master push. Action versions are
SHA-pinned with tag aliases in trailing comments.

Build:

```bash
cd docs
npm install
bash scripts/generate-api-ref.sh   # requires docfx (dotnet tool install -g docfx)
npm run build
```

The build output goes to `docs/.vitepress/dist/` (gitignored); the
generated `docs/api/` pages are also regenerated on every build and
gitignored except for the section's index.
@ottobolyos
docs: cross-link library and agent READMEs to the new docs site
f1ee8f3 
Add a Documentation section to the root README pointing at the VitePress
site under docs/ and the local-build instructions. Add a one-line
cross-reference at the top of every library / agent README so a reader
arriving at a NuGet readme can navigate to the canonical narrative page,
module catalogue entry, or wire-format reference for that library.

- README.md: Documentation section between Download and Overview.
- agent/README.md: link to docs/cli/agent, docs/configure/agent-config,
  docs/modules.
- libraries/MTConnect.NET-Common: link to docs/.
- libraries/MTConnect.NET-HTTP: link to docs/modules + docs/configure.
- libraries/MTConnect.NET-MQTT: link to docs/modules.
- libraries/MTConnect.NET-SHDR: link to docs/wire-formats/shdr and
  docs/modules.
@ottobolyos ottobolyos force-pushed the feat/vitepress-docs branch from 68a5453 to 9ed3333 Compare May 19, 2026 05:56
ottobolyos added 8 commits May 19, 2026 07:57
@ottobolyos
build(libraries): treat CS1591 as error for all production libraries
5703df0 
Add a path-conditioned libraries/Directory.Build.props that enables
GenerateDocumentationFile and promotes the "missing XML comment"
warning (CS1591) to a build error for every project under libraries/*.
The root Directory.Build.props is re-imported so version, copyright,
and package metadata still apply. Test, build, and example projects
keep the default behavior because the props file is scoped to
libraries/ only.

This makes an undocumented public API member fail the build instead
of degrading into an ignorable warning.
@ottobolyos
docs(sysml): document every member of the SysML importer model
3076f62 
Add XML doc comments to every public, internal, and private type and
member across MTConnect.NET-SysML so the importer library compiles
clean under the new CS1591-as-error gate. Covers the XMI parse model
(class, enum, property, subclass models), the per-information-model
parsers (devices, observations, assets, interfaces), the type/subtype
models, ModelHelper, MTConnectVersion, and the StringFunctions
helpers. Also drops three stale `<param name="logger">` doc lines on
XmiDeserializer that referenced a removed constructor parameter and an
unresolvable cref (CS1572/CS1574).
@ottobolyos
feat(common): regenerate from v2.7 XMI
8679bb7 
Re-run the SysML importer against the mtconnect/mtconnect_sysml_model
v2.7 tag so every .g.cs reflects the current importer output on this
tree. Picks up the WaterHardness MinimumVersion marker, drops a stale
PhysicalAsset measurement DescriptionText override, and normalizes
trailing whitespace/newlines the prior generation left behind.

mtconnect_sysml_model: 25796ac591bbe90018919fc9ccf757b4be148a92 (v2.7)
@ottobolyos
feat(sysml-import): emit XML doc comments for every generated member
ca7f476 
Add /// doc comments to the C# Scriban templates so every generated
type AND member (type-id / name-id / category / representation / units
constants, DescriptionText, TypeDescription, Min/MaxVersion overrides,
SubTypes enum, GetSubType* helpers, and all constructors) carries
contract prose sourced from the XMI element descriptions. Conditional
version/representation/units blocks now use Scriban whitespace-trim
markers so the regenerated output is byte-clean under
dotnet format (no trailing whitespace, correct indentation).

Covers the component, composition, data-item, model, enum,
enum-string, descriptions, device, interface-data-item, and
cutting-tool / pallet measurement templates.
@ottobolyos
feat(common): regenerate from v2.7 XMI with documented members
227ba1c 
Re-run the SysML importer after the template doc-comment change so
every generated .g.cs type and member under MTConnect.NET-Common
carries an XML doc comment. Diff is doc-comment-only; regen is
deterministic (a second run produces zero further change) and the
output passes dotnet format unchanged.

mtconnect_sysml_model: 25796ac591bbe90018919fc9ccf757b4be148a92 (v2.7)
@ottobolyos
feat(sysml-import): materialize CompositionState/Direction subtype vo…
bcebf6b 
…cabularies and CuttingTool Measurement base

The CompositionState and Direction event DataItems resolve their value
vocabulary from their subType, and the SysML model carries one
enumeration per subtype (CompositionStateActionEnum,
CompositionStateLateralEnum, CompositionStateMotionEnum,
CompositionStateSwitchedEnum, CompositionStateVerticalEnum,
DirectionLinearEnum, DirectionRotaryEnum). These were never collected
by the importer, leaving stale undocumented orphans that
EventValue.cs's subtype switch depends on. Collect each from the
DataTypes profile package and emit it under Observations.Events as a
strongly typed enum plus its paired *Descriptions lookup.

The SysML model declares a single Measurement class (carried under the
Pallet Measurements package) that the CuttingTool measurement
hierarchy reuses as the concrete base of ToolingMeasurement and the
per-subtype rich measurement classes. ParseCuttingTools never fed it
through the class pipeline, so the generated ToolingMeasurement.g.cs
had no MTConnect.Assets.CuttingTools.Measurement base to compile
against and the hand-authored partial had no generated partner.
Parse the shared class a second time under Assets.CuttingTools,
mirroring the abstract-Measurement handling in ParsePallets; the
renderer's existing Assets.CuttingTools.Measurement case re-emits it
as a concrete partial with its documented *Descriptions partner.
@ottobolyos
feat(common): regenerate from v2.7 XMI with documented subtype vocabu…
33f0dc2 
…laries

Re-run the SysML importer after the subtype-vocabulary and
CuttingTool-Measurement importer change. The seven CompositionState
and Direction subtype enums plus their *Descriptions lookups, and the
Assets.CuttingTools.Measurement base plus its *Descriptions partner,
are now produced fully documented. The eleven stale v2.3 generator
orphans superseded by renamed v2.7 equivalents (the CodeEnum to
MeasurementCodeEnum rename, the *Archetype/*Document description
classes, the dead Network/SensorState subtype descriptions) are no
longer produced and have been removed; ten were unreferenced dead
output and the CuttingTools MeasurementDescriptions is now a
documented regen artifact. Regen is deterministic (a second run
produces zero further change).

mtconnect_sysml_model: 25796ac591bbe90018919fc9ccf757b4be148a92 (v2.7)
@ottobolyos
docs(common): document adapter contracts, validation levels, and dele…
77700a1 
…gates

Add substantive XML doc comments to the hand-authored adapter
abstraction (AdapterEventArgs, IMTConnectAdapter,
IMTConnectAdapterModule), the InputValidationLevel policy enum, the
AssetValidationResult outcome struct, and the cross-cutting delegate
declarations in Delegates.cs. Each member describes its contract
(client-scoping, queue-versus-send semantics, validation reactions,
handler payloads) rather than restating the signature.
@ottobolyos ottobolyos force-pushed the feat/vitepress-docs branch from 8090d72 to 77700a1 Compare May 19, 2026 07:45
ottobolyos added 17 commits May 19, 2026 10:03
@ottobolyos
docs(common): document Interfaces vocabulary and Extensions helpers
7da6e72 
Add substantive XML-doc to the MTConnect.NET-Common Interfaces and
Extensions trees: Interface coordination types (bar feeder, chuck,
door, material handler), collaborator/priority/task vocabularies, and
the string/object/list/assembly conversion and hashing helpers.
@ottobolyos
docs(common): document Clients, Errors, Headers, Logging, Streams
e649ab7 
Add substantive XML-doc to the client connection-state and entity
streaming abstractions, the spec-derived request error message
constants, header attribute descriptions, the log severity enum and
log delegate, and the streams output document projection helpers.
@ottobolyos
docs(common): document Assets base contract and asset families
796ef67 
Add substantive XML-doc to the Asset/IAsset version-processing,
validation, and hashing contract and to the cutting-tool, file, raw
material, QIF, component-configuration, and pallet asset families,
explaining the per-version Process/OnProcess pipeline and the
SHA-1 content-hash composition.
@ottobolyos
docs(common): document root utility types
48e035e 
Add substantive XML-doc to the version registry, entity-type and
entity contract, the 3D position/displacement/vector/rotation value
types, the Unix-tick time conversions, the time-zone resolver, and
the debounced garbage-collection coordinator.
@ottobolyos
docs(common): document adapter send pipeline and module loader
34fa69c 
Add substantive XML-doc to MTConnectAdapter's queue/buffer send
pipeline (add/send/write/update-last for observations, assets, and
devices), the lifecycle hooks, the adapter module base class, and the
assembly-scanning module loader.
@ottobolyos
docs(common): document Configurations contracts and load/save pipeline
008296e
@ottobolyos
docs(common): document buffer index, load/retention args, and result …
aba3d1c 
…sets
@ottobolyos
docs(common): document BufferObservation storage form and asset buffe…
e091070 
…r hooks
@ottobolyos
docs(common): document ephemeral observation buffer contract
a59c2f9
@ottobolyos
docs(common): document durable file-backed asset and observation buffers
15d88c9
@ottobolyos
docs(common): document formatter result types and input/path facades
c4225c3
@ottobolyos
docs(common): document entity and response-document formatter facades
d41e4d7
@ottobolyos
docs(common): document agent metrics aggregation handlers
3c4da65
@ottobolyos
docs(common): document Input observation, asset, and data-source facades
a3d374d
@ottobolyos
docs(common): document observation output projection and small enums
582766c
@ottobolyos
docs(common): document agent module/processor extension points
5dc79ff
@ottobolyos
docs(common): document agent broker buffer indexing and constructors
c998561
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

MTConnect.NET-Development
Status: In Progress

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ottobolyos @PatrickRitchie