Update docs_deployment.md and add paths to workflow

.github/workflows/build_and_deploy.yml

@@ -1,6 +1,11 @@
 # As much as possible, this file should be kept in sync with
 # https://github.com/napari/napari/blob/main/.github/workflows/build_docs.yml
-name: Build PR Docs
+#
+# Note this workflow is also triggered by
+# https://github.com/napari/napari/blob/main/.github/workflows/deploy_docs.yml when a
+# commit to `main` occurs in `napari/napari`
+
+name: Build & Deploy PR Docs
 
 on:
   push:
@@ -25,11 +30,13 @@ jobs:
       - name: Clone docs repo
         uses: actions/checkout@v4
         with:
+          # place in '/home/runner/work/docs/docs/docs'
           path: docs  # place in a named directory
 
       - name: Clone main repo
         uses: actions/checkout@v4
         with:
+          # place in '/home/runner/work/docs/docs/napari'
           path: napari  # place in a named directory
           repository: napari/napari
           # ensure version metadata is proper
@@ -69,6 +76,8 @@ jobs:
           GOOGLE_CALENDAR_API_KEY: ${{ secrets.GOOGLE_CALENDAR_API_KEY }}
           PIP_CONSTRAINT: ${{ github.workspace }}/napari/resources/constraints/constraints_py3.10_docs.txt
         with:
+          # Runs in '/home/runner/work/docs/docs/docs'
+          # Built HTML pages in '/home/runner/work/docs/docs/docs/docs/_build/html'
           run:  make -C docs docs
           # skipping setup stops the action from running the default (tiling) window manager
           # the window manager is not necessary for docs builds at this time and it was causing
@@ -86,22 +95,22 @@ jobs:
     name: Download & Deploy Artifact
     needs: build-and-upload
     runs-on: ubuntu-latest
+    # Working directory: '/home/runner/work/docs/docs'
     steps:
       - name: Download artifact
         uses: actions/download-artifact@v4
         with:
           name: html
+          # Downloads to '/home/runner/work/docs/docs/html'
           path: html
-      - name: show files
-        run: ls -lR
 
       - name: get directory name
         # if this is a tag, use the tag name as the directory name else dev
         run: |
           if [[ "${{ github.ref }}" == "refs/tags/"* ]]; then
-            echo "branch_name=${{ github.ref_name }}" >> $GITHUB_ENV 
+            echo "branch_name=${{ github.ref_name }}" >> $GITHUB_ENV
           else
-            echo "branch_name=dev" >> $GITHUB_ENV 
+            echo "branch_name=dev" >> $GITHUB_ENV
           fi
 
       - name: Deploy Docs

docs/developers/contributing/documentation/docs_deployment.md

@@ -16,36 +16,38 @@ through several CI workflows detailed below.
     - **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 repo (`napari/napari`).
-        - This is triggered on every Pull Request and shows up as a "Build PR
-          Docs" check on the PR.
+          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-and-deploy`
-        - Triggers [`deploy_docs.yml`](https://github.com/napari/docs/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.)
+          `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_docs.yml`](https://github.com/napari/docs/blob/main/.github/workflows/build_docs.yml)
+    - **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` and builds docs locally. Uploads
-          artifacts to this repo (`napari/docs`).
-        - This is triggered on every Pull Request and shows up as a "Build PR
-          Docs" check on the PR.
-    - **Workflow file:** [`deploy_docs.yml`](https://github.com/napari/docs/blob/main/.github/workflows/deploy_docs.yml)
-        - **job:** `build-and-deploy`
-        - Builds docs locally and deploys resulting artifacts to GitHub pages at
-          the `gh-pages` branch of [napari/napari.github.io](https://github.com/napari/napari.github.io/tree/gh-pages).
+        - 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 & Uplod 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).
-        - This is triggered on any commit to the `main` branch on `napari/docs`
+        - 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 file are not identical to the `napari/napari` versions.
+    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