Skip to content

Commit d4bd6ea

Browse files
PatrickRitchiePatrickRitchie
authored
Merge pull request #181 from ottobolyos/chore/docs-route-crawler
docs(site): auto-regen hooks, auto sidebars, e2e route check
2 parents bf3e755 + 7bc43ec commit d4bd6ea

13 files changed

Lines changed: 1841 additions & 26 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -59,15 +59,25 @@ jobs:
5959
working-directory: docs
6060
run: npm ci
6161

62+
# Drift gate runs before regen — rationale lives in generate-reference.sh.
63+
- name: Verify reference pages match source (drift gate)
64+
run: bash docs/scripts/generate-reference.sh --check
65+
66+
# Generate the docfx-driven /api/ tree and the Roslyn-driven
67+
# /reference/ tree HERE — in the only job that has both the .NET SDK
68+
# and docfx installed. The downstream Build VitePress site and
69+
# Check internal links jobs receive the populated tree via the
70+
# `generated-docs` artefact; they neither install dotnet nor docfx,
71+
# so they cannot regenerate. The `prebuild` npm hook in
72+
# docs/package.json is for local dev only (where `npm run build`
73+
# implicitly regenerates); the workflow's Build step invokes
74+
# VitePress directly to skip that hook.
6275
- name: Generate API reference
6376
run: bash docs/scripts/generate-api-ref.sh
6477

6578
- name: Regenerate auto-generated reference pages
6679
run: bash docs/scripts/generate-reference.sh
6780

68-
- name: Verify reference pages match source (drift gate)
69-
run: bash docs/scripts/generate-reference.sh --check
70-
7181
# upload-artifact@v4 strips the longest common prefix from the path list
7282
# (here: 'docs/'), so the artifact root contains 'api/' + 'reference/'
7383
# rather than 'docs/api/' + 'docs/reference/'. The downstream
@@ -118,9 +128,15 @@ jobs:
118128
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
119129
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
120130

131+
# Invoke VitePress directly rather than `npm run build` to skip the
132+
# `prebuild` npm hook in docs/package.json. That hook regenerates
133+
# the /api/ + /reference/ trees, which requires the .NET SDK and
134+
# docfx — neither of which is installed in this job. The
135+
# `generated-docs` artefact downloaded above already contains the
136+
# freshly regenerated content from the prepare-docs job.
121137
- name: Build site
122138
working-directory: docs
123-
run: npm run build
139+
run: npx vitepress build
124140
env:
125141
DOCS_BASE: /MTConnect.NET/
126142

‎.github/workflows/dotnet.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,35 @@ jobs:
6565
8.0.x
6666
9.0.x
6767
68+
# MTConnect.NET-Docs-Tests carries a Category=E2E route walk
69+
# whose [OneTimeSetUp] runs `npm ci && npm run build` from
70+
# docs/ when the dist/ artifact is missing, then drives
71+
# `vitepress preview` through Microsoft.Playwright. Only the
72+
# ubuntu-latest leg runs Category=E2E (the windows-latest leg
73+
# excludes it via testFilter), so Node is only required there.
74+
- name: Setup Node.js (docs e2e prerequisite)
75+
if: matrix.os == 'ubuntu-latest'
76+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
77+
with:
78+
node-version: '20'
79+
cache: npm
80+
cache-dependency-path: docs/package-lock.json
81+
82+
# `npm run build` in docs/ invokes the `prebuild` hook
83+
# (`npm run regen`), which calls `bash scripts/generate-api-ref.sh`
84+
# → `docfx metadata` to produce the /api/ reference tree the
85+
# VitePress site consumes. The Docs-site workflow installs docfx
86+
# in its Prepare job; this workflow's E2E leg needs it for the
87+
# same reason. Only the ubuntu-latest leg runs Category=E2E
88+
# (windows-latest excludes it via testFilter), so docfx is only
89+
# required there. Without this, RouteCheckTests.OneTimeSetUp
90+
# fails with "docfx not found on PATH and ~/.dotnet/tools/docfx
91+
# is missing" — see PR #181 run 26831500675 job 79113784371.
92+
- name: Install docfx (docs e2e prerequisite)
93+
if: matrix.os == 'ubuntu-latest'
94+
run: dotnet tool install -g docfx
95+
shell: bash
96+
6897
- name: Restore dotnet tools (ReportGenerator)
6998
run: dotnet tool restore
7099

@@ -74,6 +103,34 @@ jobs:
74103
- name: Build (Debug)
75104
run: dotnet build MTConnect.NET.sln --configuration Debug --no-restore
76105

106+
# Cache Playwright browser binaries so the Category=E2E
107+
# [OneTimeSetUp] `playwright install chromium` call is a no-op on
108+
# cache hit. The key hashes the `playwright-core` package.json that
109+
# the Microsoft.Playwright NuGet copies into the build output —
110+
# that file's `version` field directly pins the chromium revision
111+
# the .NET binding drives. Hashing the csproj instead would only
112+
# invalidate by coincidence (a future PR adding an unrelated
113+
# PackageReference would invalidate; an SDK-side change to the
114+
# chromium revision would not). The step therefore runs AFTER
115+
# `dotnet build` so the file exists — placement before build
116+
# would force the key off a workspace-internal artefact (hashFiles
117+
# cannot reach the NuGet cache under ~/.nuget), so the
118+
# micro-optimisation of overlapping cache restore with build is
119+
# sacrificed for key correctness.
120+
# Both Linux (~/.cache/ms-playwright) and Windows
121+
# (%USERPROFILE%\AppData\Local\ms-playwright) paths are listed;
122+
# actions/cache restores only the path that exists on the running
123+
# OS, so the multi-path entry is safe for both matrix legs.
124+
- name: Cache Playwright browsers
125+
uses: actions/cache@v4
126+
with:
127+
path: |
128+
~/.cache/ms-playwright
129+
~\AppData\Local\ms-playwright
130+
key: ${{ runner.os }}-playwright-${{ hashFiles('**/tests/MTConnect.NET-Docs-Tests/bin/Debug/net8.0/.playwright/package/package.json') }}
131+
restore-keys: |
132+
${{ runner.os }}-playwright-
133+
77134
# MTConnect.NET-Integration-Tests is skipped here (its
78135
# IsTestProject is false unless IntegrationCoverage=true) and run
79136
# in the dedicated step below so it can use its own

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,6 +320,7 @@ $RECYCLE.BIN/
320320
node_modules/
321321
docs/.vitepress/cache/
322322
docs/.vitepress/dist/
323+
docs/.vitepress/.temp/
323324

324325
# docfx-generated API reference (regenerated by docs/scripts/generate-api-ref.sh
325326
# on every CI run; keep the section index but ignore the per-type pages).

‎docs/.vitepress/config.ts‎

Lines changed: 18 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { defineConfig } from 'vitepress';
22
import { withMermaid } from 'vitepress-plugin-mermaid';
3+
import { apiSidebar, referenceSidebar } from './sidebar';
34

45
/**
56
* VitePress config for the MTConnect.NET documentation site.
@@ -13,10 +14,15 @@ import { withMermaid } from 'vitepress-plugin-mermaid';
1314
*
1415
* @remarks
1516
* The auto-generated reference section (`/reference/`) is produced by
16-
* `build/MTConnect.NET-DocsGen` at docs-build time; do not edit those
17-
* pages by hand. Adding a new section here that should also feed the
18-
* sidebar — extend both the top `nav:` list and the matching entry in
19-
* `sidebar:`.
17+
* `build/MTConnect.NET-DocsGen` at docs-build time; the docfx-driven
18+
* API reference (`/api/`) is produced by `docs/scripts/generate-api-ref.sh`.
19+
* Do not edit those pages by hand. Both sidebars are derived from
20+
* the generated output by `./sidebar.ts` — adding a new generated
21+
* page surfaces automatically once the regen scripts have produced
22+
* it (the npm `predev` / `prebuild` hooks run them on every dev
23+
* server boot and build). Hand-curated narrative sections still
24+
* extend the top `nav:` list plus the matching `sidebar:` entry
25+
* below.
2026
*
2127
* @see {@link https://vitepress.dev/reference/site-config}
2228
*/
@@ -124,24 +130,14 @@ export default withMermaid(
124130
],
125131
},
126132
],
127-
'/api/': [
128-
{
129-
text: 'API reference',
130-
items: [{ text: 'Overview', link: '/api/' }],
131-
},
132-
],
133-
'/reference/': [
134-
{
135-
text: 'Auto-generated reference',
136-
items: [
137-
{ text: 'Overview', link: '/reference/' },
138-
{ text: 'HTTP API', link: '/reference/http-api' },
139-
{ text: 'Environment variables', link: '/reference/environment-variables' },
140-
{ text: 'Configuration schema', link: '/reference/configuration' },
141-
{ text: 'CLI reference', link: '/reference/cli' },
142-
],
143-
},
144-
],
133+
// Auto-derived from docfx's toc.yml under docs/api/. Hierarchical
134+
// by namespace dots, collapsed by default so the 1800-odd type
135+
// pages do not flood the viewport.
136+
'/api/': apiSidebar(),
137+
// Auto-derived from the .md files under docs/reference/. Flat
138+
// alphabetical list so a future page emitted by DocsGen surfaces
139+
// without a config-side edit.
140+
'/reference/': referenceSidebar(),
145141
'/wire-formats/': [
146142
{
147143
text: 'Wire formats',

0 commit comments

Comments
 (0)