Skip to content

Commit 544a331

Browse files
PatrickRitchiePatrickRitchie
authored
Merge pull request #157 from ottobolyos/feat/vitepress-docs
docs: add VitePress documentation site
2 parents 478621a + b7426d3 commit 544a331

1,644 files changed

Lines changed: 65265 additions & 11408 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
name: Docs site
2+
3+
# Build and deploy the VitePress documentation site.
4+
#
5+
# Triggers:
6+
# - push to master: build the site and deploy it to GitHub Pages.
7+
# - pull_request to master: build the site only (no deploy) so doc-breaking
8+
# changes surface in PR review.
9+
#
10+
# Action versions are pinned to commit SHAs (tag aliases appear in trailing
11+
# comments) so a tag rewrite cannot silently change what runs.
12+
on:
13+
push:
14+
branches: [ master ]
15+
pull_request:
16+
branches: [ master ]
17+
18+
# Least-privilege defaults. The deploy job overrides this with the
19+
# `pages: write` + `id-token: write` permissions GitHub Pages requires.
20+
permissions:
21+
contents: read
22+
23+
# Only one deploy can run at a time. In-progress deploys are not canceled
24+
# so that a started Pages publish gets to finish.
25+
concurrency:
26+
group: pages
27+
cancel-in-progress: false
28+
29+
env:
30+
NODE_VERSION: '20'
31+
DOTNET_VERSION: '8.0.x'
32+
33+
jobs:
34+
build:
35+
name: Build VitePress site
36+
runs-on: ubuntu-latest
37+
steps:
38+
- name: Checkout
39+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
40+
with:
41+
fetch-depth: 0
42+
43+
- name: Setup .NET
44+
uses: actions/setup-dotnet@d4c94342e560b34958eacfc5d055d21461ed1c5d # v5.0.0
45+
with:
46+
dotnet-version: ${{ env.DOTNET_VERSION }}
47+
48+
- name: Install docfx
49+
run: dotnet tool install -g docfx
50+
51+
- name: Setup Node.js
52+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
53+
with:
54+
node-version: ${{ env.NODE_VERSION }}
55+
cache: npm
56+
cache-dependency-path: docs/package-lock.json
57+
58+
- name: Install dependencies
59+
working-directory: docs
60+
run: npm ci
61+
62+
- name: Generate API reference
63+
run: bash docs/scripts/generate-api-ref.sh
64+
65+
- name: Regenerate auto-generated reference pages
66+
run: bash docs/scripts/generate-reference.sh
67+
68+
- name: Verify reference pages match source (drift gate)
69+
run: bash docs/scripts/generate-reference.sh --check
70+
71+
# Only required on push-to-master (deploy path). Computes the correct
72+
# base-path for the Pages site and writes it where later steps see it.
73+
- name: Configure GitHub Pages
74+
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
75+
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
76+
77+
- name: Build site
78+
working-directory: docs
79+
run: npm run build
80+
81+
# Upload the built artifact only on the deploy path. PR builds stop
82+
# after the build step (success / failure surfaces in the check).
83+
- name: Upload Pages artifact
84+
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
85+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
86+
with:
87+
path: docs/.vitepress/dist
88+
89+
deploy:
90+
name: Deploy to GitHub Pages
91+
needs: build
92+
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
93+
runs-on: ubuntu-latest
94+
permissions:
95+
pages: write
96+
id-token: write
97+
environment:
98+
name: github-pages
99+
url: ${{ steps.deployment.outputs.page_url }}
100+
steps:
101+
- name: Deploy
102+
id: deployment
103+
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

‎.gitignore‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,6 @@ build/MTConnect.NET.Builder/config.production.yaml
3535
gulpfile.js
3636
*.zip
3737

38-
package.json
39-
package-lock.json
40-
4138
# Visual Studio 2015 cache/options directory
4239
.vs/
4340
# Uncomment if you have tasks that create the project's static files in wwwroot
@@ -318,3 +315,13 @@ $RECYCLE.BIN/
318315

319316
# Windows shortcuts
320317
*.lnk
318+
319+
# VitePress documentation site
320+
node_modules/
321+
docs/.vitepress/cache/
322+
docs/.vitepress/dist/
323+
324+
# docfx-generated API reference (regenerated by docs/scripts/generate-api-ref.sh
325+
# on every CI run; keep the section index but ignore the per-type pages).
326+
docs/api/**
327+
!docs/api/index.md

‎MTConnect.NET.sln‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -133,9 +133,9 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect-Compliance-Tests"
133133
EndProject
134134
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}"
135135
EndProject
136-
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}"
136+
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}"
137137
EndProject
138-
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}"
138+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MTConnect.NET-DocsGen", "build\MTConnect.NET-DocsGen\MTConnect.NET-DocsGen.csproj", "{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}"
139139
EndProject
140140
Global
141141
GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -473,22 +473,22 @@ Global
473473
{E726EF85-4464-47D9-91EF-AD435D14F9D6}.Package|Any CPU.Build.0 = Debug|Any CPU
474474
{E726EF85-4464-47D9-91EF-AD435D14F9D6}.Release|Any CPU.ActiveCfg = Release|Any CPU
475475
{E726EF85-4464-47D9-91EF-AD435D14F9D6}.Release|Any CPU.Build.0 = Release|Any CPU
476-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
477-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Debug|Any CPU.Build.0 = Debug|Any CPU
478-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
479-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Docker|Any CPU.Build.0 = Debug|Any CPU
480-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Package|Any CPU.ActiveCfg = Debug|Any CPU
481-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Package|Any CPU.Build.0 = Debug|Any CPU
482-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Release|Any CPU.ActiveCfg = Release|Any CPU
483-
{AE09D1CA-5572-40BF-B984-74230E8634E1}.Release|Any CPU.Build.0 = Release|Any CPU
484-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
485-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Debug|Any CPU.Build.0 = Debug|Any CPU
486-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
487-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Docker|Any CPU.Build.0 = Debug|Any CPU
488-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Package|Any CPU.ActiveCfg = Debug|Any CPU
489-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Package|Any CPU.Build.0 = Debug|Any CPU
490-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Release|Any CPU.ActiveCfg = Release|Any CPU
491-
{3E89B860-A428-470C-8E48-0DDABC4027F0}.Release|Any CPU.Build.0 = Release|Any CPU
476+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
477+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Debug|Any CPU.Build.0 = Debug|Any CPU
478+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
479+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Docker|Any CPU.Build.0 = Debug|Any CPU
480+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Package|Any CPU.ActiveCfg = Debug|Any CPU
481+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Package|Any CPU.Build.0 = Debug|Any CPU
482+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Release|Any CPU.ActiveCfg = Release|Any CPU
483+
{B340EB29-41C8-4C64-859F-387D51F401A5}.Release|Any CPU.Build.0 = Release|Any CPU
484+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
485+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Debug|Any CPU.Build.0 = Debug|Any CPU
486+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Docker|Any CPU.ActiveCfg = Debug|Any CPU
487+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Docker|Any CPU.Build.0 = Debug|Any CPU
488+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Package|Any CPU.ActiveCfg = Debug|Any CPU
489+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Package|Any CPU.Build.0 = Debug|Any CPU
490+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Release|Any CPU.ActiveCfg = Release|Any CPU
491+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2}.Release|Any CPU.Build.0 = Release|Any CPU
492492
EndGlobalSection
493493
GlobalSection(SolutionProperties) = preSolution
494494
HideSolutionNode = FALSE
@@ -541,8 +541,8 @@ Global
541541
{94E2A2D0-71FD-4563-B1A3-FC58136017E0} = {14375E03-6BF8-45E6-B868-D2399368992B}
542542
{37320C1F-5E50-4CDF-B00D-0E0ADB4F1AE6} = {94E2A2D0-71FD-4563-B1A3-FC58136017E0}
543543
{E726EF85-4464-47D9-91EF-AD435D14F9D6} = {14375E03-6BF8-45E6-B868-D2399368992B}
544-
{AE09D1CA-5572-40BF-B984-74230E8634E1} = {14375E03-6BF8-45E6-B868-D2399368992B}
545-
{3E89B860-A428-470C-8E48-0DDABC4027F0} = {14375E03-6BF8-45E6-B868-D2399368992B}
544+
{B340EB29-41C8-4C64-859F-387D51F401A5} = {14375E03-6BF8-45E6-B868-D2399368992B}
545+
{17E64F59-0E62-4FCE-BEC4-EABBCF95B9A2} = {BBF53739-168D-4635-8595-083AC0C65E4C}
546546
EndGlobalSection
547547
GlobalSection(ExtensibilityGlobals) = postSolution
548548
SolutionGuid = {CC13D3AD-18BF-4695-AB2A-087EF0885B20}

‎README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,23 @@
3434
</tbody>
3535
</table>
3636

37+
## Documentation
38+
39+
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.
40+
41+
- **Getting started**, **Configure & Use**, **Concepts**, **Wire formats**, **Modules**, **CLI**, **Cookbook**, and **Troubleshooting** narrative pages sit under [`docs/`](docs/).
42+
- 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.
43+
- **Compliance** posture and per-version compatibility matrices sit under [`docs/compliance/`](docs/compliance/).
44+
45+
Build the site locally:
46+
47+
```bash
48+
cd docs
49+
npm install
50+
npm run build # outputs to docs/.vitepress/dist
51+
npm run dev # local dev server with hot reload
52+
```
53+
3754
## Overview
3855
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.
3956

‎adapter/Directory.Build.props‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<Project>
2+
3+
<!--
4+
Import the repository-root Directory.Build.props so its version,
5+
copyright, and package metadata still apply to every adapter
6+
project. MSBuild stops at the nearest Directory.Build.props by
7+
default, so the root one is not picked up automatically once
8+
this file exists.
9+
-->
10+
<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
11+
12+
<!--
13+
Every adapter project ships against an end-user-facing public
14+
API surface. Emit the XML documentation file and promote the
15+
"missing XML comment" warning (CS1591) to an error so an
16+
undocumented public member fails the build instead of
17+
degrading silently into a warning. Matches the policy in
18+
libraries/Directory.Build.props for the library tier.
19+
-->
20+
<PropertyGroup>
21+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
22+
<WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors>
23+
</PropertyGroup>
24+
25+
</Project>

‎adapter/MTConnect.NET-Adapter/Program.cs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@
66

77
namespace MTConnect.Applications
88
{
9+
/// <summary>
10+
/// Process entry point for the standalone <c>mtconnect.net-adapter</c>
11+
/// host. Wires the bundled <see cref="DataSource"/> implementation to
12+
/// an <see cref="MTConnectAdapterApplication"/> and runs the adapter
13+
/// in blocking mode. The CLI surface (commands such as <c>run</c>,
14+
/// <c>debug</c>, <c>install</c>, …) is implemented by
15+
/// <c>MTConnectAdapterApplication</c>; see <c>docs/reference/cli.md</c>
16+
/// for the full reference.
17+
/// </summary>
918
public class Program
1019
{
1120
// This is the Application Name shown in the Console header information
@@ -17,6 +26,14 @@ public class Program
1726
private const string ApplicationCopyright = "Copyright 2024 TrakHound Inc., All Rights Reserved";
1827

1928

29+
/// <summary>
30+
/// Process entry point. Prints the console header, instantiates
31+
/// the bundled <see cref="DataSource"/>, and delegates to
32+
/// <see cref="MTConnectAdapterApplication.Run(string[], bool)"/>
33+
/// in blocking mode.
34+
/// </summary>
35+
/// <param name="args">Command-line arguments forwarded to
36+
/// <see cref="MTConnectAdapterApplication"/>.</param>
2037
public static void Main(string[] args)
2138
{
2239
// Print an application header to the console

‎adapter/MTConnect.NET-Adapter/README.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
![MTConnect.NET Logo](https://raw.githubusercontent.com/TrakHound/MTConnect.NET/master/img/mtconnect-net-03-md.png)
2+
3+
# MTConnect.NET Adapter
4+
5+
[![MTConnect.NET](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml/badge.svg)](https://github.com/TrakHound/MTConnect.NET/actions/workflows/dotnet.yml)
6+
7+
## Overview
8+
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.
9+
10+
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.
11+
12+
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`.
13+
14+
## Usage
15+
The adapter can be run from a command-line prompt or installed as a Windows Service:
16+
17+
```
18+
adapter [help|install|install-start|start|stop|remove|debug|run|run-service] [configuration_file]
19+
20+
--------------------
21+
22+
Options :
23+
24+
help | Prints usage information
25+
install | Install as a Service
26+
install-start | Install as a Service and Start the Service
27+
start | Start the Service
28+
stop | Stop the Service
29+
remove | Remove the Service
30+
debug | Runs the Adapter in the terminal (with verbose logging)
31+
run | Runs the Adapter in the terminal
32+
run-service | Runs the Adapter as a Service
33+
34+
Arguments :
35+
--------------------
36+
37+
configuration_file | Specifies the Adapter Configuration file to load
38+
Default : adapter.config.yaml
39+
```
40+
41+
#### Example 1:
42+
Run the adapter in the terminal
43+
```
44+
adapter run
45+
```
46+
47+
#### Example 2:
48+
Run the adapter in the terminal with verbose (debug) logging
49+
```
50+
adapter debug
51+
```
52+
53+
#### Example 3:
54+
Install the adapter as a Windows Service (requires Administrator privileges)
55+
```
56+
adapter install
57+
```
58+
59+
#### Example 4:
60+
Install and immediately start the adapter as a Windows Service using a specific configuration file
61+
```
62+
adapter install-start adapter-production.yaml
63+
```
64+
65+
## Configuration
66+
The default configuration file (`adapter.config.yaml`) is shown below:
67+
68+
```yaml
69+
id: PatrickAdapter
70+
deviceKey: OKUMA-Lathe
71+
72+
modules:
73+
74+
- shdr:
75+
port: 7878
76+
77+
- mqtt:
78+
server: localhost
79+
port: 1883
80+
```
81+
82+
* `id` - A unique identifier for this adapter instance.
83+
84+
* `deviceKey` - The Name or UUID of the Device this adapter reports for.
85+
86+
* `modules` - Output module configurations. Each entry specifies the protocol used to forward observations to an MTConnect Agent.
87+
88+
For the full set of configuration properties supported by each module, see:
89+
- [MTConnect.NET-AdapterModule-SHDR](../Modules/MTConnect.NET-AdapterModule-SHDR/) — SHDR output module
90+
- [MTConnect.NET-AdapterModule-MQTT](../Modules/MTConnect.NET-AdapterModule-MQTT/) — MQTT output module
91+
92+
## Build
93+
```
94+
dotnet publish -c:Release -f:net8.0 -r:win-x64 -p:PublishSingleFile=true --self-contained false
95+
```
96+
97+
## Source Code
98+
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.
99+
100+
## Contribution / Feedback
101+
- Please use the [Issues](https://github.com/TrakHound/MTConnect.NET/issues) tab to create issues for specific problems that you may encounter
102+
- Please feel free to use the [Pull Requests](https://github.com/TrakHound/MTConnect.NET/pulls) tab for any suggested improvements to the source code
103+
- For any other questions or feedback, please contact TrakHound directly at **info@trakhound.com**.
104+
105+
## License
106+
This application and its source code is licensed under the [MIT License](https://choosealicense.com/licenses/mit/) and is free to use and distribute.

0 commit comments

Comments
 (0)