Repository navigation
docs: unified user documentation site with gt4py.cartesian and gt4py.next subsites - #3023
Conversation
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.
There was a problem hiding this comment.
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.
| 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: |
There was a problem hiding this comment.
| 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: |
| 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 |
There was a problem hiding this comment.
I think you said, you wanted to change this, but for me it's fine.
| **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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
⚙️ Agent run details
|
romanc
left a comment
There was a problem hiding this comment.
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.
Description
This PR supersedes #3005, which mixed the infrastructure with new
gt4py.nextdocumentation. The review discussion so far is there. The newgt4py.nextpages 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:
docs/user//gt4py.cartesiandocs/user/cartesian//cartesian/gt4py.nextdocs/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
docsnox session (./noxfile.py -s docs) building the three projects intodocs/user/_build/html.Documentationworkflow. 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 thedeployinput enabled allows republishing the docs of a release without a new one.docs/user/site_theme.py.gt4py.nextsubsite: the subsite infrastructure is in place (includingmyst-nbfor 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 oldQuickstartGuide.mdis removed.gt4py.nextis presented as the current generation of the library, and the cartesian-specific description and backends list are dropped.gt4py.cartesiansubsite: content unchanged. The build was broken with current Sphinx; the generated API reference now covers all subpackages exceptgt4py.nextandgt4py.eve.docsgroup):sphinxbumped to the latest release supported by each Python version (9.2 dropped Python 3.12),myst-parser>=5.2, newmyst-nb,furoandsphinx-design, removedsphinx-rtd-theme.docs/development/tools/documentation.mddescribing the infrastructure.Required before merging
gh-pagesbranch.Build documentationcheck to the required status checks of themainbranch protection, so that a broken documentation build blocks merging. The workflow now runs on every pull request (nopathsfilter) for this purpose.v*) in thegithub-pagesenvironment (Settings > Environments). It currently only allows thegh-pagesbranch, so the deployment would be rejected.Notes
gh-pagesbranch is no longer published. The oldlatest/URL redirects to the new welcome page.main(docs/user/_static/logo.svg), so it only renders once this is merged.Requirements
docs/development/tools/documentation.md.