docs: add VitePress documentation site

.github/workflows/docs.yml

@@ -0,0 +1,103 @@
+name: Docs site
+
+# Build and deploy the VitePress documentation site.
+#
+# Triggers:
+# - push to master:    build the site and deploy it to GitHub Pages.
+# - pull_request to master: build the site only (no deploy) so doc-breaking
+#   changes surface in PR review.
+#
+# Action versions are pinned to commit SHAs (tag aliases appear in trailing
+# comments) so a tag rewrite cannot silently change what runs.
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+# Least-privilege defaults. The deploy job overrides this with the
+# `pages: write` + `id-token: write` permissions GitHub Pages requires.
+permissions:
+  contents: read
+
+# Only one deploy can run at a time. In-progress deploys are not canceled
+# so that a started Pages publish gets to finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: '20'
+  DOTNET_VERSION: '8.0.x'
+
+jobs:
+  build:
+    name: Build VitePress site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@d4c94342e560b34958eacfc5d055d21461ed1c5d  # v5.0.0
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Install docfx
+        run: dotnet tool install -g docfx
+
+      - 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: Generate API reference
+        run: bash docs/scripts/generate-api-ref.sh
+
+      - name: Regenerate auto-generated reference pages
+        run: bash docs/scripts/generate-reference.sh
+
+      - name: Verify reference pages match source (drift gate)
+        run: bash docs/scripts/generate-reference.sh --check
+
+      # 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
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6.0.0
+
+      - name: Build site
+        working-directory: docs
+        run: npm run build
+
+      # Upload the built artifact only on the deploy path. PR builds stop
+      # after the build step (success / failure surfaces in the check).
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5.0.0

.gitignore

@@ -35,9 +35,6 @@ build/MTConnect.NET.Builder/config.production.yaml
 gulpfile.js
 *.zip
 
-package.json
-package-lock.json
-
 # Visual Studio 2015 cache/options directory
 .vs/
 # Uncomment if you have tasks that create the project's static files in wwwroot
@@ -318,3 +315,13 @@ $RECYCLE.BIN/
 
 # Windows shortcuts
 *.lnk
+
+# VitePress documentation site
+node_modules/
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# docfx-generated API reference (regenerated by docs/scripts/generate-api-ref.sh
+# on every CI run; keep the section index but ignore the per-type pages).
+docs/api/**
+!docs/api/index.md

MTConnect.NET.sln

@@ -133,9 +133,9 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect-Compliance-Tests"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect.NET-AgentModule-MqttRelay-Tests", "tests\MTConnect.NET-AgentModule-MqttRelay-Tests\MTConnect.NET-AgentModule-MqttRelay-Tests.csproj", "{E726EF85-4464-47D9-91EF-AD435D14F9D6}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect.NET-Tests-Agents", "tests\MTConnect.NET-Tests-Agents\MTConnect.NET-Tests-Agents.csproj", "{AE09D1CA-5572-40BF-B984-74230E8634E1}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect.NET-Docs-Tests", "tests\MTConnect.NET-Docs-Tests\MTConnect.NET-Docs-Tests.csproj", "{B340EB29-41C8-4C64-859F-387D51F401A5}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect.NET-HTTP-Tests", "tests\MTConnect.NET-HTTP-Tests\MTConnect.NET-HTTP-Tests.csproj", "{3E89B860-A428-470C-8E48-0DDABC4027F0}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect.NET-DocsGen", "build\MTConnect.NET-DocsGen\MTConnect.NET-DocsGen.csproj", "{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -473,22 +473,22 @@ Global
 		{E726EF85-4464-47D9-91EF-AD435D14F9D6}.Package|Any CPU.Build.0 = Debug|Any CPU
 		{E726EF85-4464-47D9-91EF-AD435D14F9D6}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{E726EF85-4464-47D9-91EF-AD435D14F9D6}.Release|Any CPU.Build.0 = Release|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Docker|Any CPU.Build.0 = Debug|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Package|Any CPU.ActiveCfg = Debug|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Package|Any CPU.Build.0 = Debug|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{AE09D1CA-5572-40BF-B984-74230E8634E1}.Release|Any CPU.Build.0 = Release|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Docker|Any CPU.Build.0 = Debug|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Package|Any CPU.ActiveCfg = Debug|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Package|Any CPU.Build.0 = Debug|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{3E89B860-A428-470C-8E48-0DDABC4027F0}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Docker|Any CPU.Build.0 = Debug|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Package|Any CPU.ActiveCfg = Debug|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Package|Any CPU.Build.0 = Debug|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B340EB29-41C8-4C64-859F-387D51F401A5}.Release|Any CPU.Build.0 = Release|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Docker|Any CPU.Build.0 = Debug|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Package|Any CPU.ActiveCfg = Debug|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Package|Any CPU.Build.0 = Debug|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -541,8 +541,8 @@ Global
 		{94E2A2D0-71FD-4563-B1A3-FC58136017E0} = {14375E03-6BF8-45E6-B868-D2399368992B}
 		{37320C1F-5E50-4CDF-B00D-0E0ADB4F1AE6} = {94E2A2D0-71FD-4563-B1A3-FC58136017E0}
 		{E726EF85-4464-47D9-91EF-AD435D14F9D6} = {14375E03-6BF8-45E6-B868-D2399368992B}
-		{AE09D1CA-5572-40BF-B984-74230E8634E1} = {14375E03-6BF8-45E6-B868-D2399368992B}
-		{3E89B860-A428-470C-8E48-0DDABC4027F0} = {14375E03-6BF8-45E6-B868-D2399368992B}
+		{B340EB29-41C8-4C64-859F-387D51F401A5} = {14375E03-6BF8-45E6-B868-D2399368992B}
+		{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2} = {BBF53739-168D-4635-8595-083AC0C65E4C}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {CC13D3AD-18BF-4695-AB2A-087EF0885B20}

README.md

@@ -34,6 +34,23 @@
     </tbody>
 </table>
 
+## Documentation
+
+The full documentation site is built with VitePress under [`docs/`](docs/) and published to GitHub Pages. The source lives in this repository so every change rides the same review process as the libraries.
+
+- **Getting started**, **Configure & Use**, **Concepts**, **Wire formats**, **Modules**, **CLI**, **Cookbook**, and **Troubleshooting** narrative pages sit under [`docs/`](docs/).
+- The **API reference** is generated by [docfx](https://dotnet.github.io/docfx/) from the Release `net8.0` build of every shipped library. Regenerate locally with `bash docs/scripts/generate-api-ref.sh`; the same script runs in CI ahead of every VitePress build.
+- **Compliance** posture and per-version compatibility matrices sit under [`docs/compliance/`](docs/compliance/).
+
+Build the site locally:
+
+```bash
+cd docs
+npm install
+npm run build      # outputs to docs/.vitepress/dist
+npm run dev        # local dev server with hot reload
+```
+
 ## Overview
 MTConnect.NET is a fully featured and fully Open Source **[.NET](https://dotnet.microsoft.com/)** library for **[MTConnect](https://www.mtconnect.org/)** to develop Agents, Adapters, and Clients. Supports MTConnect versions up to 2.7. A pre-compiled Agent application is available to download as well as an Adapter application that can be easily customized.
 

adapter/Directory.Build.props

@@ -0,0 +1,25 @@
+<Project>
+
+	<!--
+		Import the repository-root Directory.Build.props so its version,
+		copyright, and package metadata still apply to every adapter
+		project. MSBuild stops at the nearest Directory.Build.props by
+		default, so the root one is not picked up automatically once
+		this file exists.
+	-->
+	<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
+
+	<!--
+		Every adapter project ships against an end-user-facing public
+		API surface. Emit the XML documentation file and promote the
+		"missing XML comment" warning (CS1591) to an error so an
+		undocumented public member fails the build instead of
+		degrading silently into a warning. Matches the policy in
+		libraries/Directory.Build.props for the library tier.
+	-->
+	<PropertyGroup>
+		<GenerateDocumentationFile>true</GenerateDocumentationFile>
+		<WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
+	</PropertyGroup>
+
+</Project>

adapter/MTConnect.NET-Adapter/Program.cs

@@ -6,6 +6,15 @@
 
 namespace MTConnect.Applications
 {
+    /// <summary>
+    /// Process entry point for the standalone <c>mtconnect.net-adapter</c>
+    /// host. Wires the bundled <see cref="DataSource"/> implementation to
+    /// an <see cref="MTConnectAdapterApplication"/> and runs the adapter
+    /// in blocking mode. The CLI surface (commands such as <c>run</c>,
+    /// <c>debug</c>, <c>install</c>, …) is implemented by
+    /// <c>MTConnectAdapterApplication</c>; see <c>docs/reference/cli.md</c>
+    /// for the full reference.
+    /// </summary>
     public class Program
     {
         // This is the Application Name shown in the Console header information
@@ -17,6 +26,14 @@ public class Program
         private const string ApplicationCopyright = "Copyright 2024 TrakHound Inc., All Rights Reserved";
 
 
+        /// <summary>
+        /// Process entry point. Prints the console header, instantiates
+        /// the bundled <see cref="DataSource"/>, and delegates to
+        /// <see cref="MTConnectAdapterApplication.Run(string[], bool)"/>
+        /// in blocking mode.
+        /// </summary>
+        /// <param name="args">Command-line arguments forwarded to
+        /// <see cref="MTConnectAdapterApplication"/>.</param>
         public static void Main(string[] args)
         {
             // Print an application header to the console

adapter/MTConnect.NET-Adapter/README.md

@@ -0,0 +1,106 @@
+![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/master/img/mtconnect-net-03-md.png) 
+
+# MTConnect.NET Adapter
+
+[![MTConnect.NET](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml/badge.svg)](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml)
+
+## Overview
+This project is a ready-to-run MTConnect Adapter application. It reads data from a connected device or simulator (implemented in `DataSource.cs`) and forwards that data to an MTConnect Agent using the SHDR protocol or via MQTT, depending on which output modules are configured.
+
+The application shell is thin: `Program.cs` wires a `DataSource` instance to an `MTConnectAdapterApplication` and delegates all lifecycle management—including command-line parsing, Windows Service support, and configuration file monitoring—to the [MTConnect.NET-Applications-Adapter](../MTConnect.NET-Applications-Adapter/) library.
+
+To build your own adapter for a specific machine or controller, replace the `DataSource` class with one that reads from your hardware, then configure the output modules in `adapter.config.yaml`.
+
+## Usage
+The adapter can be run from a command-line prompt or installed as a Windows Service:
+
+```
+adapter [help|install|install-start|start|stop|remove|debug|run|run-service] [configuration_file]
+
+--------------------
+
+Options :
+
+           help  |  Prints usage information
+        install  |  Install as a Service
+  install-start  |  Install as a Service and Start the Service
+          start  |  Start the Service
+           stop  |  Stop the Service
+         remove  |  Remove the Service
+          debug  |  Runs the Adapter in the terminal (with verbose logging)
+            run  |  Runs the Adapter in the terminal
+    run-service  |  Runs the Adapter as a Service
+
+Arguments :
+--------------------
+
+  configuration_file  |  Specifies the Adapter Configuration file to load
+                         Default : adapter.config.yaml
+```
+
+#### Example 1:
+Run the adapter in the terminal
+```
+adapter run
+```
+
+#### Example 2:
+Run the adapter in the terminal with verbose (debug) logging
+```
+adapter debug
+```
+
+#### Example 3:
+Install the adapter as a Windows Service (requires Administrator privileges)
+```
+adapter install
+```
+
+#### Example 4:
+Install and immediately start the adapter as a Windows Service using a specific configuration file
+```
+adapter install-start adapter-production.yaml
+```
+
+## Configuration
+The default configuration file (`adapter.config.yaml`) is shown below:
+
+```yaml
+id: PatrickAdapter
+deviceKey: OKUMA-Lathe
+
+modules:
+
+- shdr:
+    port: 7878
+
+- mqtt:
+    server: localhost
+    port: 1883
+```
+
+* `id` - A unique identifier for this adapter instance.
+
+* `deviceKey` - The Name or UUID of the Device this adapter reports for.
+
+* `modules` - Output module configurations. Each entry specifies the protocol used to forward observations to an MTConnect Agent.
+
+For the full set of configuration properties supported by each module, see:
+- [MTConnect.NET-AdapterModule-SHDR](../Modules/MTConnect.NET-AdapterModule-SHDR/) — SHDR output module
+- [MTConnect.NET-AdapterModule-MQTT](../Modules/MTConnect.NET-AdapterModule-MQTT/) — MQTT output module
+
+## Build
+```
+dotnet publish -c:Release -f:net8.0 -r:win-x64 -p:PublishSingleFile=true --self-contained false
+```
+
+## Source Code
+This project uses the [MTConnect.NET-Applications-Adapter](../MTConnect.NET-Applications-Adapter/) library to provide the application host. Creating a custom adapter requires only implementing a `DataSource` subclass and configuring the output modules.
+
+## Contribution / Feedback
+- Please use the [Issues](https://github.com/TrakHound/MTConnect.NET/issues) tab to create issues for specific problems that you may encounter 
+- Please feel free to use the [Pull Requests](https://github.com/TrakHound/MTConnect.NET/pulls) tab for any suggested improvements to the source code
+- For any other questions or feedback, please contact TrakHound directly at **info@trakhound.com**.
+
+## License
+This application and its source code is licensed under the [MIT License](https://choosealicense.com/licenses/mit/) and is free to use and distribute.