diff --git a/.github/workflows/docs-site.yml b/.github/workflows/docs-site.yml index efa3fd916..ee238e19d 100644 --- a/.github/workflows/docs-site.yml +++ b/.github/workflows/docs-site.yml @@ -2,14 +2,21 @@ name: Documentation site # Builds the documentation site (site/, Astro Starlight) from docs/ and the source on every # pull request and push to main, so a broken page, link, anchor or docstring fails CI -# (ITL-1170). This workflow only builds: it publishes nothing. Publishing to GitHub Pages -# is a separate step the developer enables. +# (ITL-1170), and publishes it to GitHub Pages from main. +# +# Publishing: the deploy job runs on a push to main and on a manual run (Actions > +# Documentation site > Run workflow, branch main), only in metamorphic-labs/orcapod-python, +# never on a pull request. It needs Settings > Pages > Source = GitHub Actions and +# deploys in the github-pages environment, which GitHub creates. Only a run that deploys +# uploads the built site. # # The site's address comes from the repository variables DOCS_SITE_URL (origin, e.g. # https://docs.example.org) and DOCS_SITE_BASE (base path, e.g. /); one that is not # defined expands to an empty string, and the build then uses the default, # https://metamorphic-labs.github.io/orcapod-python/ (site_settings in -# scripts/docs_site_content.py). +# scripts/docs_site_content.py). They are the one source of the address: a custom domain +# is set both there (DOCS_SITE_URL=https://, DOCS_SITE_BASE=/) and in +# Settings > Pages > Custom domain. on: push: @@ -22,7 +29,9 @@ permissions: concurrency: group: docs-site-${{ github.ref }} - cancel-in-progress: true + # A newer push to a pull request cancels the older build; on main, a running build + # or deploy is never cancelled (a newer run waits). + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: build: @@ -71,3 +80,38 @@ jobs: DOCS_SITE_URL: ${{ vars.DOCS_SITE_URL }} DOCS_SITE_BASE: ${{ vars.DOCS_SITE_BASE }} run: pnpm build + + - name: Upload the site for GitHub Pages + # The same condition as the deploy job: only a run that deploys uploads. + if: >- + github.repository == 'metamorphic-labs/orcapod-python' + && github.ref == 'refs/heads/main' + && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: site/dist + + deploy: + name: Publish to GitHub Pages + needs: build + # Never on a pull request; from main only, in this repository only (a fork skips it). + if: >- + github.repository == 'metamorphic-labs/orcapod-python' + && github.ref == 'refs/heads/main' + && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + pages: write # deploy to GitHub Pages + id-token: write # verify the deployment's origin (OIDC) + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + # Two deploys never race; a running one is never cancelled. + concurrency: + group: docs-site-pages + cancel-in-progress: false + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 diff --git a/.zed/rules b/.zed/rules index 239ea31cc..563eba109 100644 --- a/.zed/rules +++ b/.zed/rules @@ -129,14 +129,23 @@ November 16, 2026, ITL-1170; site/README.md has the commands). mkdocs is gone. entry the signature does not have) fails the build. - Build locally with "cd site && pnpm install && pnpm build"; CI builds the site on every pull request (.github/workflows/docs-site.yml) and tests/test_docs/test_site_content.py runs the - content build without Node. That workflow only builds: publishing to GitHub Pages - (https://metamorphic-labs.github.io/orcapod-python/) is a separate step the developer - enables. An agent never adds a deploy job or changes a Pages setting. + content build without Node. +- The same workflow publishes the site to GitHub Pages + (https://metamorphic-labs.github.io/orcapod-python/; developer, November 17, 2026): its + deploy job runs on a push to main and on a manual run from main (Actions > Documentation + site > Run workflow), in this repository only, never on a pull request, and only a run + that deploys uploads the built site. It needs Settings > Pages > Source = GitHub Actions; + it deploys in the github-pages environment. Every page shows a banner saying the site + documents the development version (site/src/routeData.ts); it never names the current + release, and links to PyPI and the changelog instead. An agent never runs the deploy by + hand or changes a Pages setting or the github-pages environment. - The site's address is never hard-coded: DOCS_SITE_URL (origin) and DOCS_SITE_BASE (base path) come from the environment, in CI from the repository variables of the same names, with the address above when unset or empty; site_settings in - scripts/docs_site_content.py is the one place that reads and checks them. An agent never - creates or changes those variables. + scripts/docs_site_content.py is the one place that reads and checks them. A custom + domain is set in both places the developer controls: the variables + (DOCS_SITE_URL=https://, DOCS_SITE_BASE=/) and Settings > Pages > Custom domain. + An agent never creates or changes those variables. ## Linear issue tracking diff --git a/CLAUDE.md b/CLAUDE.md index 5f85624bc..9e9700e4c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -133,14 +133,23 @@ November 16, 2026, ITL-1170; `site/README.md` has the commands). mkdocs is gone. entry the signature does not have) fails the build. - Build locally with `cd site && pnpm install && pnpm build`; CI builds the site on every pull request (`.github/workflows/docs-site.yml`) and `tests/test_docs/test_site_content.py` runs - the content build without Node. That workflow only builds: publishing to GitHub Pages - (`https://metamorphic-labs.github.io/orcapod-python/`) is a separate step the developer - enables. An agent never adds a deploy job or changes a Pages setting. + the content build without Node. +- The same workflow publishes the site to GitHub Pages + (`https://metamorphic-labs.github.io/orcapod-python/`; developer, November 17, 2026): its + `deploy` job runs on a push to `main` and on a manual run from `main` (Actions > + Documentation site > Run workflow), in this repository only, never on a pull request, and + only a run that deploys uploads the built site. It needs Settings > Pages > Source = + GitHub Actions; it deploys in the `github-pages` environment. Every page shows a banner + saying the site documents the development version (`site/src/routeData.ts`); it never + names the current release, and links to PyPI and the changelog instead. An agent never + runs the deploy by hand or changes a Pages setting or the `github-pages` environment. - The site's address is never hard-coded: `DOCS_SITE_URL` (origin) and `DOCS_SITE_BASE` (base path) come from the environment, in CI from the repository variables of the same names, with the address above when unset or empty; `site_settings` in - `scripts/docs_site_content.py` is the one place that reads and checks them. An agent never - creates or changes those variables. + `scripts/docs_site_content.py` is the one place that reads and checks them. A custom + domain is set in both places the developer controls: the variables + (`DOCS_SITE_URL=https://`, `DOCS_SITE_BASE=/`) and Settings > Pages > Custom + domain. An agent never creates or changes those variables. ## Linear issue tracking diff --git a/changelog.d/ITL-1170.md b/changelog.d/ITL-1170.md index 7ff8d1614..7561fba45 100644 --- a/changelog.d/ITL-1170.md +++ b/changelog.d/ITL-1170.md @@ -2,9 +2,11 @@ - The documentation is built as an [Astro Starlight](https://starlight.astro.build) site from `docs/`, with an API reference generated from the source code on every build. CI - builds the site on every pull request; it is not published yet. mkdocs, mkdocs-material - and mkdocstrings are no longer development dependencies; `griffelib` is. Building the site - needs Node and pnpm (`site/README.md`). The site's address is configurable: `DOCS_SITE_URL` - (origin) and `DOCS_SITE_BASE` (base path), from the environment or, in CI, the repository - variables of the same names; unset or empty, it is - `https://metamorphic-labs.github.io/orcapod-python/`. (ITL-1170) + builds the site on every pull request and publishes it to GitHub Pages from `main` (on + every push to `main`, or by hand); every page says that it documents the development + version, not the latest release. mkdocs, mkdocs-material and mkdocstrings are no longer + development dependencies; `griffelib` is. Building the site needs Node and pnpm + (`site/README.md`). The site's address is configurable: `DOCS_SITE_URL` (origin) and + `DOCS_SITE_BASE` (base path), from the environment or, in CI, the repository variables of + the same names; unset or empty, it is `https://metamorphic-labs.github.io/orcapod-python/`. + (ITL-1170) diff --git a/site/README.md b/site/README.md index 3072c836e..0ad7c3c99 100644 --- a/site/README.md +++ b/site/README.md @@ -1,8 +1,8 @@ # The Orcapod documentation site An [Astro Starlight](https://starlight.astro.build) site, built from `../docs/` and the -source code. It is to be published at , -the default address (see [The site's address](#the-sites-address)). +source code. It is published from `main` at +, the default address (see [The site's address](#the-sites-address)). ## Build and preview @@ -78,14 +78,23 @@ DOCS_SITE_URL=https://docs.example.org DOCS_SITE_BASE=/ pnpm build ``` In CI, the build step takes them from the repository variables of the same names -(Settings > Secrets and variables > Actions > Variables). A custom domain is -`DOCS_SITE_URL=https://` with `DOCS_SITE_BASE=/`. +(Settings > Secrets and variables > Actions > Variables). + +A custom domain is set in two places, both repository settings: + +1. the variables: `DOCS_SITE_URL=https://` and `DOCS_SITE_BASE=/`; +2. Settings > Pages > Custom domain: ``, with the DNS record GitHub asks for + (a `CNAME` to `metamorphic-labs.github.io` for a subdomain). A site deployed by + GitHub Actions needs no `CNAME` file. + +Then run the deploy by hand (see [CI and publishing](#ci-and-publishing)) so that the +site's links use the new address. ## What is committed `package.json`, `pnpm-lock.yaml` (exact versions), `pnpm-workspace.yaml`, -`astro.config.mjs` (site settings, sidebar), `src/content.config.ts` and -this file. `node_modules/`, `dist/`, `.astro/`, `src/content/docs/` and `public/` are +`astro.config.mjs` (site settings, sidebar), `src/content.config.ts`, +`src/routeData.ts` (the banner every page shows) and this file. `node_modules/`, `dist/`, `.astro/`, `src/content/docs/` and `public/` are generated. Astro's optional image optimizer, `sharp`, is not installed (`pnpm-workspace.yaml`): the @@ -94,5 +103,20 @@ site has no images, and its `libvips` is under a license the project does not al ## CI and publishing `.github/workflows/docs-site.yml` builds the site on every pull request and push to `main`, -and checks the npm packages' licenses (`../scripts/check_site_licenses.py`). It publishes -nothing: publishing to GitHub Pages is a separate step the developer enables. +and checks the npm packages' licenses (`../scripts/check_site_licenses.py`). + +The same workflow publishes the site to GitHub Pages. Its `deploy` job +([`actions/deploy-pages`](https://github.com/actions/deploy-pages)) runs after the build: + +- on every push to `main`; +- by hand: Actions > Documentation site > Run workflow, with the branch `main` (or + `gh workflow run docs-site.yml --ref main`); +- never on a pull request, from another branch, or in a fork. + +Only a run that deploys uploads the built site (`site/dist`) as the Pages artifact. The +job deploys in the `github-pages` environment and needs Settings > Pages > Source = +GitHub Actions. Two deploys never run at once, and a running one is never cancelled. + +The site documents the development version: what is on `main`, not the latest release. +Every page says so in a banner (`src/routeData.ts`), which links to PyPI and the changelog +and never names a release. diff --git a/site/astro.config.mjs b/site/astro.config.mjs index 0ea7e0fb4..d9bc8fbd0 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -84,6 +84,8 @@ export default defineConfig({ description: 'Intuitive and powerful library for highly reproducible scientific data pipelines', plugins: [starlightLinksValidator()], + // The banner on every page: the site documents main, not a release. + routeMiddleware: './src/routeData.ts', sidebar: [ { label: 'Home', link: '/' }, page('Getting Started', 'getting-started'), diff --git a/site/src/routeData.ts b/site/src/routeData.ts new file mode 100644 index 000000000..716575a6f --- /dev/null +++ b/site/src/routeData.ts @@ -0,0 +1,15 @@ +import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; + +// Every page says that the site documents the development version: the site is +// published from main (.github/workflows/docs-site.yml), not from a release. Which +// release is current is never written here; the links lead to it. +const DEVELOPMENT_VERSION_NOTE = + 'This site documents the development version of Orcapod (the main branch), ' + + 'which may differ from the latest release. For the releases, see ' + + 'PyPI and the ' + + 'changelog.'; + +export const onRequest = defineRouteMiddleware((context) => { + const { entry } = context.locals.starlightRoute; + entry.data.banner ??= { content: DEVELOPMENT_VERSION_NOTE }; +});