ci: Implement a prim and proper release workflow

Always build the GH Pages from the default branch to ensure that the
documentation is always built with the _latest_ SMV and not e.g. a patch
version for an older release line.

Move the actual build pipeline into its own reusable workflow in order
to allow fine grained builds of the documentation and release artifacts.

Add a CI job to create a GH release draft for a new tag which
automatically attaches the released build artifacts.

.github/workflows/branch-build.yaml

@@ -0,0 +1,28 @@
+name: Build branch
+
+on:
+  push:
+    branches: [main, 'release/v*']
+  pull_request:
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python_version:
+          - '3.8'
+          - '3.9'
+          - '3.10'
+          - '3.11'
+          - '3.12'
+        os: [ubuntu-latest, windows-latest]
+        include:
+          - python_version: '3.12'
+            os: ubuntu-latest
+            upload: true
+    uses: ./.github/workflows/build.yaml
+    with:
+      runs-on: ${{ matrix.os }}
+      python-version: ${{ matrix.python_version }}
+      upload-build-artifacts: ${{ matrix.upload == true }}
+      upload-documentation-artifacts: ${{ matrix.upload == true }}

.github/workflows/build.yml → .github/workflows/build.yaml

@@ -1,33 +1,35 @@
-name: build
+name: Build
 
 on:
-  pull_request:
   workflow_call:
+    inputs:
+      ref:
+        type: string
+      runs-on:
+        type: string
+        default: 'ubuntu-latest'
+      python-version:
+        type: string
+        default: '3.12'
+      upload-documentation-artifacts:
+        type: boolean
+        default: false
+      upload-build-artifacts:
+        type: boolean
+        default: false
 
 jobs:
   build:
-    name: Build and Test Package
-    strategy:
-      matrix:
-        version:
-          - '3.8'
-          - '3.9'
-          - '3.10'
-          - '3.11'
-          - '3.12'
-        os: [ubuntu-latest, windows-latest]
-        include:
-          - version: '3.12'
-            os: ubuntu-latest
-            upload: true
-    runs-on: ${{ matrix.os }}
+    name: ${{ inputs.runs-on }} python-${{ inputs.python-version }}
+    runs-on: ${{ inputs.runs-on }}
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.version }}
-      uses: actions/setup-python@v5
       with:
-        python-version: ${{ matrix.version }}
+        ref: ${{ inputs.ref }}
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
 
     - name: Install packages
       run: pip install .
@@ -42,9 +44,9 @@ jobs:
         python -I -m sphinx_multiversion -W docs html
         cp assets/gh-pages-redirect.html html/index.html
 
-    - name: Upload the Docs
+    - name: Upload documentation artifacts
+      if: inputs.upload-documentation-artifacts
       uses: actions/upload-pages-artifact@v3
-      if: matrix.upload
       with:
         path: html/
 
@@ -54,8 +56,8 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
 
-    - name: Store the distribution packages
-      if: matrix.upload
+    - name: Upload build artifacts
+      if: inputs.upload-build-artifacts
       uses: actions/upload-artifact@v4
       with:
         name: python-package-distributions

.github/workflows/deploy-github-pages.yaml

@@ -2,9 +2,8 @@ name: Deploy docs to Github Pages
 
 on:
   push:
-    branches: [main]
-    tags:
-      - 'v*'
+    branches: [main, 'release/v*']
+    tags: ['v*']
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -14,8 +13,12 @@ concurrency:
 
 jobs:
   build:
-    if: github.ref_protected == true
-    uses: ./.github/workflows/build.yml
+    uses: ./.github/workflows/build.yaml
+    with:
+      # Always use the default branch for building the documentation
+      # Otherwise, we might build our documentation with an old SMV version
+      ref: ${{ github.event.repository.default_branch }}
+      upload-artifacts: true
 
   deploy-docs:
     name: Deploy Docs to GitHub Pages

.github/workflows/release.yaml

@@ -0,0 +1,61 @@
+name: deploy-pypi
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    name: Build the package
+    if: github.ref_protected == true
+    uses: ./.github/workflows/build.yaml
+    with:
+      upload-build-artifacts: true
+
+  deploy-pypi:
+    name: Deploy the package to ${{ matrix.environment }}.org
+    if: github.ref_protected == true
+    needs: [build]
+    strategy:
+      matrix:
+        environment: [test.pypi, pypi]
+        include:
+          - environment: pypi
+            repository: https://upload.pypi.org/legacy/
+          - environment: test.pypi
+            repository: https://test.pypi.org/legacy/
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ matrix.environment }}
+      url: https://${{ matrix.environment }}.org/p/sphinx-multiversion
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download the build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish Distributions to ${{ matrix.environment }}.org
+        uses: pypa/gh-action-pypi-publish@fb13cb306901256ace3dab689990e13a5550ffaa
+        with:
+          repository-url: ${{ matrix.repository }}
+
+  create-release:
+    name: Create the GitHub Release
+    if: github.ref_protected == true
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download the build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Create the release draft with the build artifacts
+        uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8
+        with:
+          draft: true
+          files: dist/*