Add Jupyter Book documentation

.github/workflows/ci_cd.yaml

@@ -30,6 +30,29 @@ jobs:
           user: __token__
           password: ${{ secrets.PYPI }}
           skip-existing: true
+  publish-docs:
+    name: Publish documentation
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for all tags and branches
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Install package
+        run: pip install -e ".[dev]"
+      - name: Build Jupyter Book
+        run: make documentation
+      - name: Deploy documentation
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: docs/_build/html
   lint:
     runs-on: ubuntu-latest
     name: Lint
@@ -47,7 +70,7 @@ jobs:
         run: black . -l 79 --check
 
   test:
-    name: Build and Test
+    name: Build and test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -68,6 +91,8 @@ jobs:
         run: make data
       - name: Run tests
         run: pytest
+      - name: Test documentation builds
+        run: make documentation
   check-version:
     name: Check version
     if: github.event_name == 'pull_request'

.gitignore

@@ -11,3 +11,4 @@
 !incomes.csv
 !tax_benefit.csv
 !demographics.csv
+**/_build

Makefile

@@ -19,7 +19,7 @@ docker:
 	docker buildx build --platform linux/amd64 . -t policyengine-uk-data:latest
 
 documentation:
-	streamlit run docs/Home.py
+	jb clean docs && jb build docs
 
 data:
 	python policyengine_uk_data/datasets/frs/dwp_frs.py

docs/_config.yml

@@ -0,0 +1,22 @@
+title: PolicyEngine UK data
+author: PolicyEngine
+copyright: "2024"
+logo: logo.png
+
+execute:
+  execute_notebooks: off
+
+repository:
+  url: https://github.com/policyengine/policyengine-uk-data
+  branch: master
+  path_to_book: docs
+
+sphinx:
+  config:
+    html_js_files:
+    - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.7/require.min.js
+    html_theme: furo
+    pygments_style: default
+    html_css_files:
+      - style.css
+    nb_remove_code_source: true

docs/_static/style.css

@@ -0,0 +1,2 @@
+@import url('https://fonts.googleapis.com/css2?family=Roboto+Serif:[email protected]&family=Roboto:wght@300&display=swap');
+

docs/_toc.yml

@@ -0,0 +1,5 @@
+format: jb-book
+root: intro
+chapters:
+- file: methodology.ipynb
+- file: validation.ipynb

docs/Home.py → docs/intro.md

@@ -1,16 +1,5 @@
-import streamlit as st
-from policyengine_uk_data.utils.download_docs_prerequisites import (
-    download_data,
-)
+# Introduction
 
-download_data()
-
-st.set_page_config(layout="wide")
-
-st.title("PolicyEngine-UK-Data")
-
-st.write(
-    """
 PolicyEngine-UK-Data is a package that creates representative microdata for the UK, 
 designed for input in the PolicyEngine tax-benefit microsimulation model. This tool 
 allows users to explore the data sources, validation processes, and enhancements 
@@ -22,5 +11,4 @@
 * An accurate representation of the current UK household sector *now*.
 
 This repository is dedicated to the second of those. In this documentation, we'll explain how we do that, but we'll also use our model (the first bullet) to see what we end up with when we combine the two, and measure up against other organisations doing the same thing.
-"""
-)
+