Skip to content

docs: unified user documentation site with gt4py.cartesian and gt4py.next subsites - #3023

Merged
egparedes merged 6 commits into
mainfrom
docs-site-infrastructure
Nov 20, 2026
Merged

egparedes merged 6 commits into
mainfrom
docs-site-infrastructure

Conversation

@egparedes

@egparedes egparedes commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

This PR supersedes #3005, which mixed the infrastructure with new gt4py.next documentation. The review discussion so far is there. The new gt4py.next pages follow in a stacked PR on top of this one.

Sets up a single user documentation site, deployed to GitHub Pages, made of three independent Sphinx projects built into one tree:

Site Sources Published at
Welcome page docs/user/ /
gt4py.cartesian docs/user/cartesian/ /cartesian/
gt4py.next docs/user/next/ /next/

The welcome page introduces the project and links to both subsites, which can also be browsed on their own and link back to each other.

Changes

  • Build: new docs nox session (./noxfile.py -s docs) building the three projects into docs/user/_build/html.
  • Deployment: new Documentation workflow. It builds the site on every pull request and deploys it to GitHub Pages only when a (non-pre) release is published. A manual run from a release tag with the deploy input enabled allows republishing the docs of a release without a new one.
  • Theme: all sites use Furo (light/dark mode), configured once in docs/user/site_theme.py.
  • gt4py.next subsite: the subsite infrastructure is in place (including myst-nb for executable MyST notebooks), but it only contains a placeholder page saying that the documentation is being rewritten and will be available soon. The new documentation follows in the stacked PR. The old QuickstartGuide.md is removed.
  • README: gt4py.next is presented as the current generation of the library, and the cartesian-specific description and backends list are dropped.
  • gt4py.cartesian subsite: content unchanged. The build was broken with current Sphinx; the generated API reference now covers all subpackages except gt4py.next and gt4py.eve.
  • Dependencies (docs group): sphinx bumped to the latest release supported by each Python version (9.2 dropped Python 3.12), myst-parser>=5.2, new myst-nb, furo and sphinx-design, removed sphinx-rtd-theme.
  • Developer docs: new docs/development/tools/documentation.md describing the infrastructure.

Required before merging

  • Switch the Pages source of the repository to GitHub Actions (Settings > Pages). The site is currently served from the gh-pages branch.
  • Add the Build documentation check to the required status checks of the main branch protection, so that a broken documentation build blocks merging. The workflow now runs on every pull request (no paths filter) for this purpose.
  • Allow deployments from the release tags (v*) in the github-pages environment (Settings > Environments). It currently only allows the gh-pages branch, so the deployment would be rejected.

Notes

  • The documentation is published when the next release is made after this PR is merged, so the old site stays up until then. After the switch, the old v1.0 documentation in the gh-pages branch is no longer published. The old latest/ URL redirects to the new welcome page.
  • The README logo now loads from main (docs/user/_static/logo.svg), so it only renders once this is merged.
  • The advanced toolchain guides and the workshop notebooks are not part of the site yet.

Requirements

  • All fixes and/or new features come with corresponding tests.
  • Important design decisions have been documented in the appropriate ADR inside the docs/development/ADRs/ folder: not an ADR, see docs/development/tools/documentation.md.

Add the infrastructure for a single user documentation site: a welcome page
and independent Sphinx subsites for gt4py.cartesian and gt4py.next (Furo
theme), a 'docs' nox session, a GitHub Pages deployment workflow, and the
related README and developer documentation. The gt4py.next subsite only
contains a placeholder page for now.
@egparedes
egparedes added this pull request to stack #3025 November 20, 2026 11:47
@egparedes
egparedes marked this pull request as ready for review November 20, 2026 12:15
@egparedes
egparedes requested a balanced review from Copilot November 20, 2026 12:15

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

Comment thread README.md Outdated
GT4Py uses the Sphinx tool for the documentation. To build browseable HTML documentation, install the required tools provided in the `docs` dependency group:
The user documentation is published at [gridtools.github.io/gt4py](https://GridTools.github.io/gt4py). It is a welcome page linking to two independent subsites, one for `gt4py.cartesian` and one for `gt4py.next`, whose sources live in [`docs/user/`](./docs/user) (the welcome page), [`docs/user/cartesian/`](./docs/user/cartesian) and [`docs/user/next/`](./docs/user/next).

GT4Py uses the Sphinx tool for the documentation, with pages written in reStructuredText (`gt4py.cartesian`) or [MyST](https://myst-parser.readthedocs.io) Markdown (welcome page and `gt4py.next`). MyST pages with a `jupytext` header declaring the `myst` format are notebooks, which are executed when the site is built. To build the whole site in a dedicated environment, run the `docs` nox session:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
GT4Py uses the Sphinx tool for the documentation, with pages written in reStructuredText (`gt4py.cartesian`) or [MyST](https://myst-parser.readthedocs.io) Markdown (welcome page and `gt4py.next`). MyST pages with a `jupytext` header declaring the `myst` format are notebooks, which are executed when the site is built. To build the whole site in a dedicated environment, run the `docs` nox session:
GT4Py uses the Sphinx tool for the documentation, with pages written in reStructuredText (`gt4py.cartesian`) or [MyST](https://myst-parser.readthedocs.io) Markdown (welcome page and `gt4py.next`). To build the whole site in a dedicated environment, run the `docs` nox session:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in f4c04db.

Comment thread docs/user/index.md
framework, a set of libraries and utilities to develop performance portable
applications in this area.

Currently, two generations live side by side in the library: `gt4py.next` and

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you said, you wanted to change this, but for me it's fine.

Comment thread README.md Outdated
**NOTE:** The `gt4py.next` subpackage contains a new version of GT4Py which is not compatible with the current _stable_ version defined in `gt4py.cartesian`. The new version is still experimental.
**NOTE:** GT4Py contains two generations of the library, which are not compatible with each other. `gt4py.next` is the current one, where most of the active development happens, and the one to choose for new projects. `gt4py.cartesian` is the previous generation, limited to Cartesian grids: it is still maintained for the models relying on it and enriched with features where needed.

## 📃 Description

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that the below is still for cartesian so we should emphasize this somewhere for now or change the README, either by dropping it or e.g. putting examples of both next to each other.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped the cartesian-specific Description and backends list from the README in d9c3ae5; the README now only has the intro and the NOTE about the two generations.

@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
✅ Merge recommendation: Needs review
🔎 Failure modes

What: When executable notebooks are added to the `next` subsite (the stacked PR announced in the description), myst-nb execution artifacts (executed .ipynb files and cell outputs) may be published to the live site. The `docs` session cleans `html/jupyter_execute`, but myst-nb conventionally writes `jupyter_execute` inside the build output folder, which for the subsite build is `html/next/` — so the cleanup may target the wrong path. No notebooks exist yet, so this is currently inert and the actual artifact location is unverified in this PR.
Where: noxfile.py:docs
Trigger: The stacked PR adds MyST notebooks under docs/user/next and the site is built and deployed.
Detected by: nothing — the build succeeds either way; the extra files would only be visible in the deployed site artifact.
Covered in this PR: No

What: Broken cross-site navigation links could ship to production. All links between the three sites are hand-written relative `.html` paths (`site_links` in each `conf.py`, the card `link:` options in `docs/user/index.md`, raw HTML links in `docs/user/next/index.md`, and `pathto()` in the shared sidebar template). Sphinx does not resolve or validate `.html` targets, and the new workflow only builds the site — it never runs `linkcheck` or inspects the output tree.
Where: docs/user/_templates/gt4py-site-links.html
Trigger: A typo in one of the relative paths (e.g. `../cartesian/index.html`) or a renamed/moved page in a subsite.
Detected by: nothing — the build succeeds; broken links are only visible by manually browsing the built artifact uploaded on PRs.
Covered in this PR: No

What: Old deep links into the previously published documentation break. Only the entry URL `/latest/` is redirected to the new welcome page; every deeper legacy URL (e.g. `/latest/next/QuickstartGuide.html` or specific old cartesian pages under `/latest/`) now returns 404, and `QuickstartGuide.md` is deleted outright.
Where: noxfile.py:docs
Trigger: External tutorials, papers, or bookmarks pointing at specific pages of the old published docs rather than the `/latest/` root.
Detected by: nothing automated — 404s would surface as user reports.
Covered in this PR: No

🏅 Score: 86
🧪 No relevant tests
🔒 No security concerns identified
🔀 No multiple PR themes
⚡ No major issues detected

⚙️ Agent run details
  • Model: openai/zai-org/GLM-5.3-Flash
  • Tokens: 17,487 in / 38,775 out / 56,262 total
  • Time cost: 362.2s
  • AI calls: 1

@egparedes egparedes changed the title docs: unified user documentation site with cartesian and next subsites docs: unified user documentation site with gt4py.cartesian and gt4py.next subsites Nov 20, 2026

@romanc romanc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.

I ran the new nox command locally and briefly browsed the docs locally. It looks nicer as you said.

I noticed a bunch of warnings while building the cartesian docs. We might fix them in a Christmas cleanup.

@egparedes
egparedes merged commit abb8300 into main Nov 20, 2026
34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants