From 55f5146952d1d03f9cef3df327243b645240cc5b Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 1 Aug 2025 12:18:34 -0700 Subject: [PATCH 1/4] Add additional detail about the site deployment pipeline --- .../documentation/docs_deployment.md | 143 +++++++++++------- 1 file changed, 87 insertions(+), 56 deletions(-) diff --git a/docs/developers/contributing/documentation/docs_deployment.md b/docs/developers/contributing/documentation/docs_deployment.md index 544c92c67..b7015981e 100644 --- a/docs/developers/contributing/documentation/docs_deployment.md +++ b/docs/developers/contributing/documentation/docs_deployment.md @@ -3,65 +3,96 @@ # Documentation and website deployment ```{note} -This guide is intended for napari core contributors and is not required reading -for regular contributors. If you're looking for information on how to contribute +This guide targets core team members doing deployments. Curious contributors may +find it interesting. If you're looking for information on how to contribute to the documentation, see [](contributing-docs). ``` -The napari documentation and website sources are spread over three repositories, -and these are connected and used to generate the documentation and website -through several CI workflows detailed below. - -1. [`napari/napari`](https://github.com/napari/napari) - - **Workflow file:** [`build_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml) - - **job:** `build-and-upload` - - Pulls in sources from `napari/docs` and builds docs locally. Uploads - artifacts to this repository (`napari/napari`). - - This is triggered on any push to a branch named 'docs*' or tag named 'v*', - to `napari/napari`. The artifact can be used to check the documentation - but is not used for docs deployment. - - **Workflow file:** [`deploy_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml) - - **job:** `build-napari-docs` - - Triggers [`build_and_deploy.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml) - workflow at the [napari/docs](https://github.com/napari/docs) repo. - Waits for results and reports it. - - This is triggered on any commit to the `main` branch on - `napari/napari` (and consequently triggers a new deployment of the - `napari.org` website). When the commit is tagged, the `build_and_deploy.yml` - workflow will deploy to the version folder e.g., '{{ napari_version }}/'. - -2. [`napari/docs`](https://github.com/napari/docs) - - **Workflow file:** [`build_and_deploy.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml) - - **job:** `build-and-upload` - - Pulls in sources from `napari/napari`, builds docs, then uploads as an - artifact named 'html' to this repository (`napari/docs`). - - This is triggered on every Pull Request and shows up as a "Build & Deploy PR - Docs / Build & Upload Artifact" check on the PR. - - **job:** `deploy` - - Downloads the artifact from the `build-and-upload` job and deploys the html - to GitHub pages at the `gh-pages` branch of - [napari/napari.github.io](https://github.com/napari/napari.github.io/tree/gh-pages). - - Always deploys to the `dev/` folder on `napari.github.io` (version - "latest" on the website). - - Deployment is triggered by any commit to the `main` branch on `napari/docs` - (and consequently triggers a new deployment of the `napari.org` - website.) - - Note that these files are not identical to the `napari/napari` version. - -3. [`napari/napari.github.io`](https://github.com/napari/napari.github.io) - - Contains built documentation files (.html) for all versions in the - `gh-pages` branch. Auto-deploys to `gh-pages` on every commit (which in - turn happens on every commit to the `main` branches of either - `napari/napari` or `napari/docs`). - - For every commit to the `gh-pages` branch of this repo, the - [`unversioned_pages.yml` action](https://github.com/napari/napari.github.io/blob/gh-pages/.github/workflows/unversioned_pages.yml) - is triggered and copies the latest contents of the index page and the dev - folder over the "stable" version of the documentation. This ensures that - both the landing page of the website and the developer documentation, - including the contributing guide, are always up to date. - -## Notes +Deploying the napari website, which includes our documentation, requires the +orchestration of workflows across multiple repositories. The following +repos provide logic for the deployment pipeline: +- [`napari/napari-sphinx-theme`](https://github.com/napari/napari-sphinx-theme) +- [`napari/docs`](https://github.com/napari/docs) +- [`napari/napari`](https://github.com/napari/napari) +- [`napari/napari.github.io`](https://github.com/napari/napari.github.io) + +## Site deployment pipeline + +### From source files to html artifact ([`napari/docs`](https://github.com/napari/docs)) + +The deployment pipeline begins with the source files found in `napari/docs`. +The `napari/docs` repo contains the website and documentation source files. +It uses the `napari/napari-sphinx-theme` to scaffold structure and styling. + +**Workflow file:** [`build_and_deploy.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml) +- **job:** `build-and-upload` + - Pulls in sources from `napari/napari`, builds docs, then uploads as an + artifact named 'html' to this repository (`napari/docs`). + - This is triggered on every Pull Request and shows up as a "Build & Deploy PR + Docs / Build & Upload Artifact" check on the PR. +- **job:** `deploy` + - Downloads the artifact from the `build-and-upload` job and deploys the html + to GitHub pages at the `gh-pages` branch of + [napari/napari.github.io](https://github.com/napari/napari.github.io/tree/gh-pages). + - Always deploys to the `dev/` folder on `napari.github.io` (version + "latest" on the website). + - Deployment is triggered by any commit to the `main` branch on `napari/docs` + (and consequently triggers a new deployment of the `napari.org` + website.) + + + +```{note} +The html artifact files created by the `build_and_deploy.yml` workflow are not +identical to the html files built by the `napari/napari` workflows. +``` +## From html artifact to deployment trigger ([`napari/napari`](https://github.com/napari/napari)) + +**Workflow file:** [`build_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml) +- **job:** `build-and-upload` +- Pulls in sources from `napari/docs` and builds docs locally. Uploads + artifacts + + to this repository (`napari/napari`). +- Any push to a branch named 'docs*' or tag named 'v*', to `napari/napari` + triggers this workflow. The artifact can be used to check the documentation + but is not used for docs deployment. + +**Workflow file:** [`deploy_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml) +- **job:** `build-napari-docs` +- Triggers [`build_and_deploy.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_and_deploy.yml) + workflow at the [napari/docs](https://github.com/napari/docs) repo. + Waits for results and reports it. +- This is triggered on any commit to the `main` branch on + `napari/napari` (and consequently triggers a new deployment of the + `napari.org` website). When the commit is tagged, the `build_and_deploy.yml` + workflow will deploy to the version folder e.g., '{{ napari_version }}/'. + +## From deployment trigger to a live site [`napari/napari.github.io`](https://github.com/napari/napari.github.io) + +- Contains built documentation files (.html) for all versions in the + `gh-pages` branch. Auto-deploys to `gh-pages` on every commit (which in + turn happens on every commit to the `main` branches of either + `napari/napari` or `napari/docs`). +- For every commit to the `gh-pages` branch of this repo, the + [`unversioned_pages.yml` action](https://github.com/napari/napari.github.io/blob/gh-pages/.github/workflows/unversioned_pages.yml) + is triggered and copies the latest contents of the index page and the dev + folder over the "stable" version of the documentation. This ensures that + both the landing page of the website and the developer documentation, + including the contributing guide, are always up to date. + +### Unversioned pages + +The website and documentation is designed to support the concept of +**unversioned pages**. These pages will display the same content for any +documentation version and offers the reader the +most up-to-date and consistent information, such as community norms, project +roadmaps, and governance. +These pages do add a bit more complexity as there is a need to move and copy files +so they are the same across version. The `unversioned_pages.yml` action +does this work. + +## CircleCI for tests and previews CircleCI is set up in both `napari/napari` and `napari/docs`, but doesn't deploy documentation. It serves to test the docs build and to provide documentation From ee23f3b73c6c9105b1c75b3d1351c1a9e3f022db Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 1 Aug 2025 12:28:09 -0700 Subject: [PATCH 2/4] fix headings --- .../contributing/documentation/docs_deployment.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/developers/contributing/documentation/docs_deployment.md b/docs/developers/contributing/documentation/docs_deployment.md index b7015981e..cfbbfedb0 100644 --- a/docs/developers/contributing/documentation/docs_deployment.md +++ b/docs/developers/contributing/documentation/docs_deployment.md @@ -40,20 +40,16 @@ It uses the `napari/napari-sphinx-theme` to scaffold structure and styling. (and consequently triggers a new deployment of the `napari.org` website.) - - ```{note} The html artifact files created by the `build_and_deploy.yml` workflow are not identical to the html files built by the `napari/napari` workflows. ``` -## From html artifact to deployment trigger ([`napari/napari`](https://github.com/napari/napari)) +### From html artifact to deployment trigger ([`napari/napari`](https://github.com/napari/napari)) **Workflow file:** [`build_docs.yml`](https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml) - **job:** `build-and-upload` - Pulls in sources from `napari/docs` and builds docs locally. Uploads - artifacts - - to this repository (`napari/napari`). + artifacts to this repository (`napari/napari`). - Any push to a branch named 'docs*' or tag named 'v*', to `napari/napari` triggers this workflow. The artifact can be used to check the documentation but is not used for docs deployment. @@ -68,7 +64,7 @@ identical to the html files built by the `napari/napari` workflows. `napari.org` website). When the commit is tagged, the `build_and_deploy.yml` workflow will deploy to the version folder e.g., '{{ napari_version }}/'. -## From deployment trigger to a live site [`napari/napari.github.io`](https://github.com/napari/napari.github.io) +### From deployment trigger to a live site [`napari/napari.github.io`](https://github.com/napari/napari.github.io) - Contains built documentation files (.html) for all versions in the `gh-pages` branch. Auto-deploys to `gh-pages` on every commit (which in @@ -81,7 +77,7 @@ identical to the html files built by the `napari/napari` workflows. both the landing page of the website and the developer documentation, including the contributing guide, are always up to date. -### Unversioned pages +## Unversioned pages The website and documentation is designed to support the concept of **unversioned pages**. These pages will display the same content for any From acab48db09bbb443091befe06e60b7d22202d598 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 1 Aug 2025 12:40:59 -0700 Subject: [PATCH 3/4] Add explicit statement for served files location --- docs/developers/contributing/documentation/docs_deployment.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/developers/contributing/documentation/docs_deployment.md b/docs/developers/contributing/documentation/docs_deployment.md index cfbbfedb0..eba57af2d 100644 --- a/docs/developers/contributing/documentation/docs_deployment.md +++ b/docs/developers/contributing/documentation/docs_deployment.md @@ -16,6 +16,8 @@ repos provide logic for the deployment pipeline: - [`napari/napari`](https://github.com/napari/napari) - [`napari/napari.github.io`](https://github.com/napari/napari.github.io) +The files served to the web are found in the `gh-pages` branch of the `napari/napari.github.io` repo. + ## Site deployment pipeline ### From source files to html artifact ([`napari/docs`](https://github.com/napari/docs)) From e6d6a12f843e2f22630e18b9b20454b21ae5bdc7 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 15 Aug 2025 13:03:00 -0700 Subject: [PATCH 4/4] Add link to action as suggested by melissawm MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- docs/developers/contributing/documentation/docs_deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/docs_deployment.md b/docs/developers/contributing/documentation/docs_deployment.md index eba57af2d..d00fe5145 100644 --- a/docs/developers/contributing/documentation/docs_deployment.md +++ b/docs/developers/contributing/documentation/docs_deployment.md @@ -87,7 +87,7 @@ documentation version and offers the reader the most up-to-date and consistent information, such as community norms, project roadmaps, and governance. These pages do add a bit more complexity as there is a need to move and copy files -so they are the same across version. The `unversioned_pages.yml` action +so they are the same across version. The [`unversioned_pages.yml` action](https://github.com/napari/napari.github.io/blob/gh-pages/.github/workflows/unversioned_pages.yml) does this work. ## CircleCI for tests and previews