docs: VitePress documentation site#157
Draft
ottobolyos wants to merge 101 commits into
Draft
Conversation
Contributor
|
It looks like the package.json file may be missing. Possibly filtered out of the git? |
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>
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.
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.
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.
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.
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.
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).
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.
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.
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.
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
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.
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.
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.
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
force-pushed
the
feat/vitepress-docs
branch
from
f2e0087 to
33ca82f
Compare
ottobolyos
force-pushed
the
feat/vitepress-docs
branch
from
33ca82f to
28ea57a
Compare
ottobolyos
force-pushed
the
feat/vitepress-docs
branch
3 times, most recently
from
817519c to
d9388ce
Compare
…kflow Stand up a VitePress site rooted at the existing top-level docs/ directory, absorb the legacy hand-written top-level .md pages and the img/ tree into the new section structure, and add a docs.yml GitHub Actions workflow that builds and deploys the site to GitHub Pages on master push. Top-level layout includes Compliance, Configure and Use, Concepts, API reference, Wire formats, Modules, CLI, Cookbook, and Troubleshooting sections, each rooted at docs/<section>/index.md. The Mermaid plugin is enabled so every architecture, sequence, class-relationship, state-machine, and wire-flow diagram can be authored inline. A docfx config and api-reference shell script provide the per-type pages for the API reference section, regenerable via bash docs/scripts/generate-api-ref.sh.
Add /// summaries to every public type, member, event, delegate, and field across MTConnect.NET-Common so the docfx pass under docs/api/ has a complete description per symbol. Covers adapter contracts, agent broker buffer indexing and the observation lifecycle, agent module/processor extension points, asset families, buffer durability hooks, configuration load and save pipelines, the formatter result types and entity and response-document formatter facades, ephemeral and durable file-backed buffers, input observation/asset/data- source facades, the agent metrics aggregation handlers, root utility types, Component, Composition, DataItem, Device, Agent, and Observation public APIs, the IObservation.Validate contract, device value/lookup/ search helpers, the device document and container interfaces, the observation description and value types, data-set and table entry types, condition, event, sample, data-set, table, and time-series observations and codecs, and the ValueKeys vocabulary. No behavioral change.
Add /// summaries to every public member of the SysML importer model that ships from MTConnect.NET-SysML, so the docfx pass produces a complete per-symbol description for the importer model. No behavioral change.
Add /// summaries to every public type and member of MTConnect.NET-TLS, covering the TLS certificate configuration types. No behavioral change.
Add /// summaries to the Windows Service host wrappers in MTConnect.NET-Services. No behavioral change.
Add /// summaries to every public type and member across MTConnect.NET-XML, covering the XML response document and entity formatters, the XmlFunctions helpers, every surrogate type, the response document, error document/error, the path and streams formatters, and the streams response reader and writer. Includes the dotnet format pass that normalizes indentation across the touched files.
Add /// summaries to every public type and member across MTConnect.NET-JSON. Covers the entity and response document formatters, JsonFunctions helpers, parameter/input formatters, every surrogate type, the streams/devices/assets headers, ComponentStream, DeviceStream, every observation form (Condition, Event, Sample, DataSet, Table, TimeSeries), specification (including entry/cell definitions, process spec, spec limits, control/alarm limits), the configuration parameters and QIF wrapper assets, the CuttingTool asset and life cycle, ProcessFeedrate, ProcessSpec, ParameterSet, ToolDefinition, the abstract asset / file asset / file property / location / comment, the devices/streams/assets documents, table cell, recondition count, archetype ref, item collection, and parameter set surrogates. Plus the dotnet format pass that normalizes indentation across the touched files.
Add /// summaries to every public type and member across MTConnect.NET-JSON-cppagent. Covers the HTTP and MQTT entity formatters, event/sample/measurement/component formatters, every surrogate type, the assets/streams/devices documents, the assets header, observation and cutting-tool asset, the cutting tool life cycle and cutting item, every cutting-tool collection (recondition ref, archetype ref, cutting item collection), the destination, cell, and constraints value, the data-item definition, data-set/table samples and events, every typed device container, the relationship/reference containers and filter, the conditions handler, sample-value converter, the destination/cutter status, archetype, MQTT entity, and the outer response envelopes. Plus the dotnet format pass that normalizes indentation across the touched files.
Add /// summaries to every public type and member across MTConnect.NET-HTTP excluding the Ceen request-handler classes (which land in a separate commit alongside the docs-gen tool extraction plumbing). Covers HTTP headers, encodings, request types, output validation, URL helpers, the PathProcessor, server input args, format options, stream args, response struct, static file request, client/server configuration members and HTTP adapter component URIs, the probe/current/sample/client URI builders and DNS resolver, the client stream lifecycle including events, dispatch loop, and content decoding, the server fields and start/stop, and the server stream events and lifecycle. Plus the dotnet format pass that normalizes indentation across the touched files.
Add /// summaries to every public type and member across MTConnect.NET-MQTT. Covers the connection status, format, response-handler delegate, message factory, input devices, observation, and observations batch payloads, the client/document server/entity server configuration members, the MQTT client and expanded client lifecycle, events, and properties, the broker class properties, events, and start/stop lifecycle, the document server and entity server publish surface, and the MQTT relay class properties, events, and start/stop/dispose. Plus the dotnet format pass that normalizes indentation across the touched files.
Add /// summaries to every public type and member across MTConnect.NET-SHDR. Covers the agent client, SHDR adapter component URI, client configurations, the line tokens, observation classifier, data-set entry, table cell and entry, the data-set, table, time-series, fault state, message and condition observation constructors and clear-fault states, the SHDR data item and device wire-protocol surface, the asset wire-protocol designators / constructors / detect / read / parse, the agent listener events and lifecycle, the interval and queue adapters, the SHDR adapter client constructors and device-bound dispatch overrides, the SHDR client constants, constructors, start/stop, and override points, the SHDR adapter constructors, internal references, lifecycle hooks, and the adapter write-line / data-item / message / condition / time-series / data-set / table / asset add/send surface. Plus the dotnet format pass that normalizes indentation across the touched files.
Add /// summaries to every public type and member of MTConnect.NET-DeviceFinder, covering the address/port ranges, the discovered-device record, and the finder events and constructors. Includes the dotnet format pass that normalizes indentation across the touched files.
Add /// doc-comments to every Ceen request-handler class in
libraries/MTConnect.NET-HTTP/Servers/, covering the endpoint
(HTTP method plus path template), what the handler does, and the
round-trip behavior (response document format negotiation, query
parameters, streaming upgrade where relevant).
The eight handlers are:
- MTConnectProbeResponseHandler — GET /probe and GET /{deviceKey}/probe
(plus the bare GET / alias).
- MTConnectCurrentResponseHandler — GET /current and
GET /{deviceKey}/current; multipart x-mixed-replace when interval is
supplied.
- MTConnectSampleResponseHandler — GET /sample and
GET /{deviceKey}/sample; multipart x-mixed-replace when interval is
supplied.
- MTConnectAssetsResponseHandler — GET /assets and
GET /{deviceKey}/assets.
- MTConnectAssetResponseHandler — GET /asset/{assetId}.
- MTConnectStaticResponseHandler — file serving driven by the agent's
FileConfiguration entries.
- MTConnectPutResponseHandler — PUT / and PUT /{deviceKey}.
- MTConnectPostResponseHandler — POST / and POST /asset/{assetId}.
These /// summaries are the source of the per-endpoint description on
docs/reference/http-api.md; the docs-gen tool parses them via Roslyn
rather than carrying a hand-curated copy.
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. Lands after the per-library docs commits so the gate is satisfiable from this point forward.
Update the Scriban templates under build/MTConnect.NET-SysML-Import to emit /// summaries for every generated type, member, enum value, and description. Covers the C# templates (Devices.ComponentType, Devices.CompositionType, Devices.DataItemType, Devices.Device, Assets.CuttingToolMeasurement, Pallets.Measurement, Interfaces.InterfaceDataItemType, Enum, EnumDescriptions, EnumString, EnumStringDescriptions, Model, ModelDescriptions), the JSON-cppagent templates (Components, Events, Measurements, Samples), and the XML templates (XmlCuttingItem, XmlCuttingToolLifeCycle, XmlMeasurements). The regenerated .g.cs they emit are committed as part of the per-library docs commits earlier in this series. No behavioral change to the generator itself; the change is purely documentation surface in the emitted code.
…g, narrative pages, examples Add the narrative content for the VitePress site: - Wire-formats deep-dives — XML, JSON v1, JSON-CPPAGENT v2, JSON-CPPAGENT-MQTT, SHDR; sample envelopes, codec class names, Mermaid diagrams for the wire-flow handshakes. - CLI reference — Agent CLI, Adapter CLI, sysml-import, tools/dotnet.sh, tools/test.sh. - Module catalog — HTTP server, HTTP adapter, MQTT broker, MQTT relay, MQTT output, SHDR adapter, SHDR output. - Concept pages — Devices, Components, Compositions, DataItems, Observations, Assets, Relationships. - Compliance — per-version matrix, wire-format compliance, spec cross-references, known divergences, test harness. - Configure and Use — install / configure agent / configure adapter / configure modules and integration recipes (InfluxDB, MQTT-AWS, MQTT-HiveMQ, OpenSSL). - 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, MQTT TLS handshake issues. - Examples — runnable per-topic samples. - Development — contributor-facing onboarding.
Add build/MTConnect.NET-DocsGen — a Roslyn-syntax-only tool that walks the repository source tree (no compiled assemblies required) and emits three reference pages under docs/reference/: - http-api.md — every HTTP endpoint exposed by an MTConnect.NET agent, separated by transport (Ceen / AspNetCore). Per-endpoint detail blocks pull their description text from the /// doc-comment on each Ceen request-handler class (added in docs(ceen) earlier) and from the /// on each AspNetCore controller method. - environment-variables.md — every Environment.GetEnvironmentVariable read site discovered in source. - configuration.md — the YAML/JSON option-class schema derived from every public ConfigurationOptions class. Plus docs/reference/index.md (the landing page) and the IndexRenderer that emits the auto-generated banner. Usage: dotnet run --project build/MTConnect.NET-DocsGen -- --repo . --check verifies the on-disk pages are in sync without rewriting them (returns 1 on drift). The solution file is updated in this same commit to add the new project under the build/ folder.
Add tests/MTConnect.NET-Docs-Tests with a DocsReferenceGenerationTests fixture that re-runs the Roslyn inventories from build/MTConnect.NET-DocsGen and asserts the on-disk markdown under docs/reference/ is identical to what the generator would produce. Five tests cover the four generated pages (http-api.md, environment-variables.md, configuration.md, index.md) plus an inverse check that no docs/reference/http-api.md endpoint heading references a route that no longer exists in source. Adding a new HTTP endpoint, env-var read, or config property without regenerating the reference therefore fails CI. The solution file is updated in this same commit to add the new test project under tests/.
Add docs/scripts/generate-reference.sh as the canonical entry point for regenerating and --check-verifying the auto-generated reference pages. The script wraps dotnet run --project build/MTConnect.NET-DocsGen and is wired into the docs CI workflow alongside the API-reference step. The dotnet workflow already builds and tests the whole solution (which now includes the validation test project), so reference drift is caught there as well.
ottobolyos
force-pushed
the
feat/vitepress-docs
branch
2 times, most recently
from
ae35d66 to
903215a
Compare
docfx renders C# <c>...</c> XML-doc tags as raw <code>...</code>
HTML in the emitted markdown. VitePress passes that markdown through
the Vue template compiler, which interprets {{ ... }} inside the <code>
element as a mustache interpolation. The SysML representation markers
(<c>{{term(data set)}}</c> in MTConnectDataItemType /// summaries)
trip the compiler with "Error parsing JavaScript expression" because
"term(data set)" has an unquoted space, breaking the entire site
build.
Mark every emitted <code> opener with v-pre so Vue treats its
contents as literal text and skips template parsing. Applied as a
post-docfx sed pass in docs/scripts/generate-api-ref.sh; safe to
re-run because the clean step above the sed wipes the output tree
before docfx writes fresh files.
Local verification: regenerated 1843 reference pages and ran
`npm run build` to completion (exit 0, 705s) — first repro of the
exact CI failure with a pre-patch build, then green with the patch.
Refs: build VitePress site CI step on 903215a — pre-fix failure at
api/MTConnect.SysML.Models.Devices.MTConnectDataItemType.md (210:10).
The reference-generation tool no longer emits docs/reference/tsdoc.md (removed alongside the docfx-driven /// extraction effort). The shell script's banner-comment file list still named it, which misleads anyone reading the script for the source of truth. Strip the line.
The module catalogue covered every shipped agent module and adapter
module, but the only shipped agent processor — MTConnect Python Agent
Processor under agent/Processors/MTConnect.NET-AgentProcessor-Python —
had no narrative page anywhere under docs/. Configure & Use briefly
named the YAML key under `processors:`, but did so against the wrong
runtime ('Python.NET' vs. the project's actual IronPython engine).
Add docs/modules/agent-processor-python.md modelled on the shipped
module pages: identifier and NuGet block, configuration schema, a
Mermaid wire-interaction diagram showing the processor's hop between
adapter intake and buffer write, the README's three example scripts
(EMERGENCY_STOP, PATH_FEEDRATE_OVERRIDE, TIME_SERIES derivation),
scripting-environment caveats (IronPython, no native CPython
extensions, ProcessObservation API surface), and troubleshooting
pointers.
Add the new section 'Agent processors — shipped' to modules/index.md
between the agent-modules and adapter-modules tables — processors sit
one hop earlier than modules and the catalogue page now reflects that.
Add an 'Agent processors' group to the /modules/ sidebar in
.vitepress/config.ts between the existing 'Agent modules' and
'Adapter modules' groups.
Correct configure/agent-config.md to point at the new page and
replace the inaccurate 'Python.NET' reference with the actual
IronPython runtime.
Local verification: `npm run build` exit 0, 813s; site builds with
the new page in the sidebar and all cross-links resolving.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
tools/dotnet.sh,tools/test.sh, and SysML importer.Auto-generated API reference
The API reference under
docs/api/is generated by docfx from the Debugnet8.0build of every shipped library DLL plus its XML doc file. The configuration lives atdocs/.docfx/docfx.json; the regeneration script atdocs/scripts/generate-api-ref.shcompiles each library with-p:GenerateDocumentationFile=trueand then runsdocfx metadata, producing a flatNamespace.Type.mdlayout 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.mdis the only tracked file underdocs/api/.The legacy v1
MTConnect.Assets.Json.CuttingTools.JsonProcessFeedrateshadows the cppagent v2JsonProcessFeedRateon a case-insensitive module path; the legacy type is excluded viadocs/.docfx/filter.ymlso the module resolver does not collide on the case-variant pair. The cppagent v2 type stays in the reference.Documentation gate
libraries/Directory.Build.propstreats 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-SysMLis extended so the CompositionState and Direction event subtype value vocabularies (one enumeration per subtype) and the shared CuttingToolMeasurementbase are materialized as documented generated output instead of stale orphan files. TheMTConnect.NET-Commonlibrary 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.ymlruns on every push and pull request to master. Each run sets up .NET 8.0 and Node 20, installs docfx, runsdocs/scripts/generate-api-ref.sh, thennpm run buildinsidedocs/. On push to master the built site is uploaded as a Pages artifact and thedeployjob publishes it to GitHub Pages. Action versions are SHA-pinned with tag aliases in trailing comments.docs/package.jsonlives insidedocs/; a!docs/package.jsonallow-list entry was added to.gitignorebecause the repository's blanketpackage.jsonignore targets the legacy gulp-era build artefacts.