adjust docs

Author: melonora

.github/workflows/gh-pages.yml

@@ -1,26 +1,50 @@
-name: GitHub Pages
+name: Deploy Docs
 
 on:
   release:
-    types:
-      - created
+    types: [created]
+  pull_request:
+    branches: [main]
 
 jobs:
-  job:
-    name: GitHub Pages
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.13"
-      - name: Install project dependencies
+      - name: Install dependencies
         run: pip install -e ".[dev]"
+      - name: Generate versions.json
+        run: |
+          cat <<EOF > docs/versions.json
+          [
+            {
+              "version": "latest",
+              "url": "/xarray-dataclass/latest/"
+            },
+            {
+              "version": "stable",
+              "url": "/xarray-dataclass/stable/"
+            }
+          ]
+          EOF
       - name: Build docs
-        run: python -m sphinx -b html docs docs/_build
+        run: |
+          # Set DOCS_VERSION env var according to event
+          if [[ "${{ github.event_name }}" == "release" ]]; then
+            export DOCS_VERSION=stable
+          else
+            export DOCS_VERSION=latest
+          fi
+
+          python -m sphinx -b html docs docs/_build
+      - name: Copy versions.json to build output
+        run: cp docs/versions.json docs/_build/
       - name: Deploy docs
         uses: peaceiris/actions-gh-pages@v3
         with:
-          force_orphan: true
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/_build
+          destination_dir: ${{ github.event_name == 'release' && 'stable' || 'latest' }}

README.md

@@ -67,7 +67,7 @@ pixi add --pypi xarray-dataclasses
 
 ## Basic usage
 
-xarray-dataclasses uses [the Python's dataclass].
+xarray-dataclass uses [the Python's dataclass].
 Data (or data variables), coordinates, attributes, and a name of DataArray or Dataset objects will be defined as dataclass fields by special type hints (`Data`, `Coord`, `Attr`, `Name`), respectively.
 Note that the following code is supposed in the examples below.
 
@@ -378,25 +378,24 @@ pixi run pre-commit-install
 ```
 
 ### Testing, linting, and formatting
-We have [a test workflow][test-workflow] for testing, static type checking, linting, and formatting the code.
-It is used for status checks when a pull request is created.
-If you would like to check them in local, the following commands are almost equivalent (the difference is that the workflow is run under multiple Python versions).
+We have a test workflow for testing and a pre-commit workflow for static type checking, linting, and formatting the code.
+It is performed when a pull request is created against main.
+If you would like to check them in local, the following commands are almost equivalent (the difference is that the test workflows are run under multiple Python versions).
 Furthermore, these tasks are defined only in the `dev` environment. Pixi does not require you to specify the environment
 in that case.
 
-```shell
+```
 pixi run tests
-pixi run flake8
-pixi run black
-pixi run pyright
+pixi run -e dev pre-commit run --all-files
 ```
 
 ### Creating documentation
-We also have a [documentation workflow] (Add link). However, if you want to locally create the documentation
+We also have a documentation workflow. However, if you want to locally create the documentation
 run the following:
 
 ```shell
-pixi run doc_build
+pixi run doc_build # this just creates the build
+pixi run doc_serve # build and serve at http://localhost:8000/
 ```
 
 ### Create a release

docs/conf.py

@@ -1,6 +1,11 @@
+import os
+
+version = os.environ.get("DOCS_VERSION", "unknown")
+release = version
+
 # project information
-author = "Akio Taniguchi"
-copyright = "2020-2024 Akio Taniguchi"
+author = "Wouter-Michiel Vierdag"
+copyright = "2025 Wouter-Michiel Vierdag"
 
 
 # general configuration
@@ -31,6 +36,10 @@
         "image_light": "logo-light.svg",
         "image_dark": "logo-dark.svg",
     },
-    "github_url": "https://github.com/astropenguin/xarray-dataclasses/",
-    "twitter_url": "https://twitter.com/astropengu_in/",
+    "switcher": {
+        "json_url": "https://xarray-contrib.github.io/xarray-dataclass/versions.json",
+        "version_match": version,
+    },
+    "github_url": "https://github.com/xarray-contrib/xarray-dataclass/",
+    "twitter_url": "https://x.com/xarray_dev/",
 }

pixi.lock

@@ -74,6 +74,7 @@ dev = { features = ["dev"], solve-group = "default" }
 [tool.pixi.feature.dev.tasks]
 tests = "pytest"
 doc_build = { cmd = "sphinx-apidoc -efT -o docs/_apidoc src/xarray_dataclasses && sphinx-build -a docs docs/_build" }
+doc_serve = { cmd = "sphinx-build -a docs docs/_build && python -m http.server --directory docs/_build 8000" }
 
 [tool.pyright]
 reportMissingImports = "none"