V7.0 prerelease #371
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
| 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: | |
| prepare-docs: | |
| name: Prepare generated docs | |
| 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 | |
| # Drift gate runs before regen — rationale lives in generate-reference.sh. | |
| - name: Verify reference pages match source (drift gate) | |
| run: bash docs/scripts/generate-reference.sh --check | |
| # Generate the docfx-driven /api/ tree and the Roslyn-driven | |
| # /reference/ tree HERE — in the only job that has both the .NET SDK | |
| # and docfx installed. The downstream Build VitePress site and | |
| # Check internal links jobs receive the populated tree via the | |
| # `generated-docs` artefact; they neither install dotnet nor docfx, | |
| # so they cannot regenerate. The `prebuild` npm hook in | |
| # docs/package.json is for local dev only (where `npm run build` | |
| # implicitly regenerates); the workflow's Build step invokes | |
| # VitePress directly to skip that hook. | |
| - 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 | |
| # upload-artifact@v4 strips the longest common prefix from the path list | |
| # (here: 'docs/'), so the artifact root contains 'api/' + 'reference/' | |
| # rather than 'docs/api/' + 'docs/reference/'. The downstream | |
| # download-artifact steps in the build and check-links jobs restore the | |
| # 'docs/' prefix via 'path: docs'. This v4 behaviour differs from v3 | |
| # (which preserved the upload paths verbatim), so the two ends must stay | |
| # in sync if either is touched. | |
| - name: Upload generated docs | |
| uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 | |
| with: | |
| name: generated-docs | |
| path: | | |
| docs/api | |
| docs/reference | |
| if-no-files-found: error | |
| retention-days: 1 | |
| build: | |
| name: Build VitePress site | |
| needs: prepare-docs | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| with: | |
| fetch-depth: 0 | |
| - 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: Download generated docs | |
| uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 | |
| with: | |
| name: generated-docs | |
| path: docs | |
| # 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 | |
| # Invoke VitePress directly rather than `npm run build` to skip the | |
| # `prebuild` npm hook in docs/package.json. That hook regenerates | |
| # the /api/ + /reference/ trees, which requires the .NET SDK and | |
| # docfx — neither of which is installed in this job. The | |
| # `generated-docs` artefact downloaded above already contains the | |
| # freshly regenerated content from the prepare-docs job. | |
| - name: Build site | |
| working-directory: docs | |
| run: npx vitepress build | |
| env: | |
| DOCS_BASE: /MTConnect.NET/ | |
| # The flat 2 000-page API reference plus the unified server + | |
| # client bundles push rollup past the GitHub Actions runner's | |
| # default Node heap (~4 GB) during the markdown -> Vue | |
| # transform. The previous symptom was 'Ineffective | |
| # mark-compacts near heap limit' aborting the build with | |
| # exit 134 even though no page actually fails to parse. Lift | |
| # the cap to 8 GB -- runners have 16 GB of RAM, so this is | |
| # well within budget. | |
| NODE_OPTIONS: --max-old-space-size=8192 | |
| # 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 | |
| check-links: | |
| name: Check internal links | |
| needs: prepare-docs | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| with: | |
| fetch-depth: 0 | |
| - 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: Download generated docs | |
| uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 | |
| with: | |
| name: generated-docs | |
| path: docs | |
| - name: Check internal links | |
| working-directory: docs | |
| run: npm run check-links | |
| 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 |