chore(Docs): build the docs in CI and publish on merge to master - #2210
Merged
Merged
Conversation
The site's srcDir is docs/, so a relative link out of that tree resolves to no page and fails the build. Every other reference to a repository root file already uses an absolute URL.
Add docs.yml, running composer docs:build on pull requests against master and 5.x. gh-pages.yml gains a push trigger on master so the published site follows master without a manual dispatch, a concurrency group so two merges cannot race onto the gh-pages branch, and a dry_run expression that only a workflow_dispatch can make true.
`docs/package-lock.json` has been ignored since zircote#1084, when `vitepress build` only ever ran from a manual dispatch and there was nothing to keep reproducible. Running it on every pull request changes that premise: `docs.yml` already reads the lockfile for the npm cache and `npm ci`, so without it the check cannot resolve a cache path and fails before it builds anything. - Track `docs/package-lock.json`. - Give `gh-pages.yml` `setup-node` and `npm ci`, as `spec-validation.yml` already does. It ran a bare `npm install` against no lockfile, so the published site was built from whatever `vitepress: ^1.6` resolved to that day. - Watch `npm` in `/` and `/docs` with dependabot, grouped into one pull request. The root lockfile has had no update path since zircote#2045 added it.
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
1 participant
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.
Overview
The documentation site is built with
vitepress, which fails the build on a dead link.Nothing ran that build before a merge:
gh-pages.ymlisworkflow_dispatchonly, andcomposer docs:checkverifies documented code against the source without resolving links.A dead link introduced in #2204 merged green and sat on
masteruntil the next manualdeploy, which failed and pointed at the dispatch rather than at the commit behind it.
Publishing had the same manual step — the site followed
masteronly when someoneremembered to dispatch it.
Building the docs on every pull request also makes the toolchain worth pinning.
docs/package-lock.jsonhas been ignored since #1084, whenvitepress buildonly ever ranfrom a manual dispatch and there was nothing to keep reproducible. Without it the new check
cannot resolve an npm cache path and fails before it builds anything, and the deploy — a bare
npm installagainst no lockfile — published whatevervitepress: ^1.6resolved to on theday. Tracking it puts the check and the deploy on the same versions.
Changes
.github/workflows/docs.yml, runningcomposer docs:buildon pull requests.gh-pages.ymlon pushes tomaster, with a concurrency group and adry_runonly a dispatch can set.
docs/package-lock.json, and givegh-pages.ymlsetup-nodeandnpm ci, asspec-validation.ymlalready does.npmin/and/docswith dependabot, grouped into one pull request. The rootlockfile has had no update path since Replace Spectral with Redocly for spec validation #2045 added it.
ROADMAP.mdfromdocs/dev/testing.mdby URL, as the other references torepository root files already do.