Update docs

Author: AndyRae

.github/workflows/publish-pypi.yml

@@ -2,6 +2,10 @@
 
 This sample workflow demonstrates a complete release pipeline that combines semantic versioning, container publishing, and automated tagging. It's designed to be copied into your project's `.github/workflows/` directory and customised for your specific needs.
 
+The idea is to provide a drop-in model for releasing software, where developers can focus on code, rather than the mechanics of releases. The developer only has to make the decision of what type of release (patch, minor, major, none) and communicate this through their PR title. The workflow then takes care of the rest - generating release notes, creating GitHub releases, building and publishing container images, and tagging them appropriately.
+
+This exists within the existing constraints of Github, mostly that [automated releases cannot trigger other workflows](https://github.com/orgs/community/discussions/25281), so by composing reusable workflows together we can achieve a full release pipeline that is still easy to understand and maintain. The workflow is also designed to be flexible, so you can easily swap out the container publishing step for other types of release artifacts if needed.
+
 ## Overview
 
 The workflow performs the following steps:
@@ -37,6 +41,7 @@ Uses the [`publish-container.yml`](../publish-container.md) reusable workflow to
 - Push to the specified container registry
 
 **Parameters:**
+
 - `image-name`: Name of your container image
 - `image-description`: Description for the image
 - `registry`: Container registry (e.g., `ghcr.io`, `docker.io`)
@@ -52,6 +57,7 @@ Uses the [`semver-container.yml`](../semver-container.md) reusable workflow to:
 - Only runs if `semantic-release` created a new release
 
 **Parameters:**
+
 - `image-name`: Must match the `publish-container` job
 - `registry`: Must match the `publish-container` job
 - `tag`: Release tag from semantic-release (do not modify)
@@ -67,7 +73,7 @@ uses: health-informatics-uon/workflows/.github/workflows/semantic-release.yml@v1
 Check the [releases](https://github.com/health-informatics-uon/workflows/releases) for available versions.
 
 ## Usage
-   
+
 1. Copy `samples/release.container.yaml` to your repository's `.github/workflows/release.yaml`
 2. Copy `samples/release.config.js` to your repository root and customise it for your repository
 3. Update the workflow parameters in `release.yaml` (image name, etc.)

docs/samples/release.container.md

@@ -0,0 +1,54 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+  
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/omop-lite
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1