Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 48 additions & 4 deletions .github/workflows/docs-site.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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://<domain>, DOCS_SITE_BASE=/) and in
# Settings > Pages > Custom domain.

on:
push:
Expand All @@ -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:
Expand Down Expand Up @@ -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
19 changes: 14 additions & 5 deletions .zed/rules
Original file line number Diff line number Diff line change
Expand Up @@ -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://<domain>, DOCS_SITE_BASE=/) and Settings > Pages > Custom domain.
An agent never creates or changes those variables.

## Linear issue tracking

Expand Down
19 changes: 14 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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://<domain>`, `DOCS_SITE_BASE=/`) and Settings > Pages > Custom
domain. An agent never creates or changes those variables.

## Linear issue tracking

Expand Down
14 changes: 8 additions & 6 deletions changelog.d/ITL-1170.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
40 changes: 32 additions & 8 deletions site/README.md
Original file line number Diff line number Diff line change
@@ -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 <https://metamorphic-labs.github.io/orcapod-python/>,
the default address (see [The site's address](#the-sites-address)).
source code. It is published from `main` at
<https://metamorphic-labs.github.io/orcapod-python/>, the default address (see [The site's address](#the-sites-address)).

## Build and preview

Expand Down Expand Up @@ -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://<domain>` 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://<domain>` and `DOCS_SITE_BASE=/`;
2. Settings > Pages > Custom domain: `<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
Expand All @@ -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.
2 changes: 2 additions & 0 deletions site/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
Expand Down
15 changes: 15 additions & 0 deletions site/src/routeData.ts
Original file line number Diff line number Diff line change
@@ -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 <code>main</code> branch), ' +
'which may differ from the latest release. For the releases, see ' +
'<a href="https://pypi.org/project/orcapod/#history">PyPI</a> and the ' +
'<a href="https://github.com/metamorphic-labs/orcapod-python/blob/main/CHANGELOG.md">changelog</a>.';

export const onRequest = defineRouteMiddleware((context) => {
const { entry } = context.locals.starlightRoute;
entry.data.banner ??= { content: DEVELOPMENT_VERSION_NOTE };
});
Loading