Book setup

.github/workflows/ci.yaml

@@ -19,7 +19,6 @@ jobs:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
       - run: uv sync --locked --all-extras --dev
-      - run: uv run ruff check .
-      - run: uv run ruff format --check .
+      - run: uv run ruff check --output-format=github .
       - run: uv run pytest
       - run: uv build

.github/workflows/deploy_docs.yaml

@@ -0,0 +1,45 @@
+name: deploy_docs
+
+on:
+  push:
+    branches: [main]
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+
+      - name: cache executed notebooks
+        uses: actions/cache@v4
+        with:
+          path: docs/_build/.jupyter_cache
+          key: jupyter-book-cache-${{ hashFiles('uv.lock') }}
+
+      # Build the book
+      - name: Build the book
+        run: uv run jupyter-book build docs
+
+      # Upload the book's HTML as an artifact
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_build/html
+
+      # Deploy the book's HTML to GitHub Pages
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -216,3 +216,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# MyST build outputs
+_build

docs/_config.yml

@@ -0,0 +1,25 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Pystagegate Docs
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/ONSDigital/pystagegate  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+sphinx:
+  extra_extensions:
+  - 'sphinx.ext.autodoc'

docs/_toc.yml

@@ -0,0 +1,8 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+  - file: demos
+  - file: api

docs/api.rst

@@ -0,0 +1,5 @@
+API Reference
+=============
+
+.. automodule:: pystagegate.functions
+    :members:

docs/demos.ipynb

@@ -0,0 +1,36 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1524f811",
+   "metadata": {},
+   "source": [
+    "# Pystagegate Demos\n",
+    "\n",
+    "Executable notebook demonstrating code usage"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10a6dcf2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "from pystagegate.functions import filler\n",
+    "\n",
+    "df = pd.DataFrame({\"A\": [1, 2, 3], \"B\": [4, 5, 6]})\n",
+    "\n",
+    "filler(df)"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/intro.md

@@ -0,0 +1,4 @@
+# Introduction to Pystagegate
+
+Pystagegate is a Python package implementing Stage Gate automated quality assurance methods for demographic data. 
+Stage Gate methods were designed by the Office of National Statistics Population and Migration R&D division.

pyproject.toml

@@ -20,8 +20,10 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "jupyter-book<2.0",
     "pytest>=9.0.3",
     "ruff>=0.15.13",
+    "sphinx>=7.4.7",
 ]
 
 [tool.ruff.lint]

src/pystagegate/functions.py

@@ -2,4 +2,13 @@
 
 
 def filler(df: pd.DataFrame) -> pd.DataFrame:
+    """Filler function for testing autodoc
+
+    Args:
+        df: A pandas DataFrame.
+
+    Returns:
+        A pandas DataFrame.
+    """
+
     return df