Switch to quarto; panache for quarto formatting

.github/workflows/release.yml

@@ -19,16 +19,19 @@ jobs:
         with:
           fetch-depth: 2
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
       - name: Set up Python
-        uses: actions/setup-python@v5.3.0
-        with:
-          python-version: "3.10"
+        run: uv python install
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Install Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
         with:
-          # Install a specific version of uv.
-          version: "0.5.15"
+          version: "1.5.57"
 
       - name: Check if there is a parent commit
         id: check-parent-commit
@@ -63,16 +66,16 @@ jobs:
         run: |
           sudo apt-get -y install openssl graphviz nano texlive graphviz-dev unzip build-essential
 
-      - name: Install dependencies
+      - name: build the book
         run: |
-          uv sync
-
-      - name: Build book
-        run: uv run jupyter-book build . --verbose
+          uv run quarto render --execute
+        env:
+            # This forces Quarto to use the Python inside your uv venv
+            QUARTO_PYTHON: ${{ github.workspace }}/.venv/bin/python
 
       - name: Publish
         if: steps.check-version.outputs.tag
-        run: uv run ghp-import -n -p -f _build/html
+        run: uv run quarto publish gh-pages --no-render --no-browser
 
       - name: Publish the release notes
         uses: release-drafter/release-drafter@v6.0.0

.github/workflows/tests.yml

@@ -1,8 +1,13 @@
 name: tests
 
 on:
-  - pull_request
-  - push
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   pre-commit:
@@ -22,16 +27,19 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: Set up Python
-        uses: actions/setup-python@v5.3.0
-        with:
-          python-version: "3.10"
-
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Install Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
         with:
-          # Install a specific version of uv.
-          version: "0.5.2"
+          version: "1.5.57"
 
       - name: set timezone
         run: |
@@ -42,13 +50,9 @@ jobs:
         run: |
           sudo apt-get -y install openssl graphviz nano texlive graphviz-dev unzip build-essential
 
-      - name: Install dependencies
-        run: |
-          uv sync
-
       - name: build the book
         run: |
-          uv run jupyter-book build . --verbose
+          uv run quarto render --execute
 
       - name: success
         run: |

.gitignore

@@ -1,8 +1,12 @@
 # Mac
 .DS_Store
 
-# jupyterbook
-_build/**
+# quarto
+_book/
+/.quarto/
+**/*.quarto_ipynb
+_freeze/
+.panache*
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.pre-commit-config.yaml

@@ -28,3 +28,7 @@ repos:
       # Run the formatter.
       - id: ruff-format
         types_or: [python, pyi, jupyter]
+  - repo: https://github.com/jolars/panache
+    rev: v2.32.0  # Use the latest release version
+    hooks:
+      - id: panache-format

README.md

@@ -18,23 +18,23 @@ When you make a pull request, pre-commit and build will run automatically, and f
 
 ## Installing the development environment locally
 
-You will need installations of Python 3.10 and [**uv**](https://docs.astral.sh/uv/). **uv** can be used to install certain distributions of Python through the `uv python install 3.10` command but you can use other Python installations.
+You will need installations of Python 3.10 and [**uv**](https://docs.astral.sh/uv/). **uv** can be used to install certain distributions of Python through the `uv python install 3.12` command but you can use other Python installations.
 
 Clone this repository.
 
 To install the development environment, run `uv sync` from the project root. This should create a `.venv/` directory with the Python4DS environment in it. You can check that the environment has been installed by running `uv run python -V` in the project root directory.
 
 ## Building the book
 
-The book is compiled from source markdown and Jupyter notebook files [**jupyter-book**](https://jupyterbook.org/en/stable/) package.
+The book is compiled from source markdown and Jupyter notebook files using [**Quarto**](https://quarto.org/). You will need Quarto installed on your system — see the [Quarto installation guide](https://quarto.org/docs/get-started/).
 
 To build the book, run
 
 ```bash
-uv run jupyter-book build .
+uv run quarto render --execute
 ```
 
-Once this command is run, you should be able to look at the HTML files for the book locally on your computer. They will be in `_build`. The project is configured to stop the build if any errors are encountered. This is a frequent occurrence! You'll need to look at the logs to work out what might have gone wrong.
+Once this command is run, you should be able to look at the HTML files for the book locally on your computer. They will be in `_book`. The `freeze: auto` setting means only notebooks whose source has changed will be re-executed on subsequent builds.
 
 ## Uploading the book
 
@@ -46,10 +46,10 @@ This repo is configured such that new versions automatically build and upload th
 
 You shouldn't need to upload the book if you are a regular contributor. There are times when you might need to as an admin, but normally the book will be updated automatically upon release of a new version.
 
-See [here](https://jupyterbook.org/publish/gh-pages.html) for how to upload revised HTML files, but the key command is
+First build the book, then publish with:
 
 ```bash
-uv run ghp-import -n -p -f _build/html
+uv run quarto publish gh-pages --no-render --no-browser
 ```
 
 ## Code hygiene
@@ -78,7 +78,7 @@ on your staged files. Ensure pre-commit reports all tests as having passed befor
 
 ## Running and developing in a Docker container
 
-There is a Dockerfile associated with this project. Pre-reqs
+There is a Dockerfile associated with this project.
  To use it:
 
 1. Pre-reqs: docker installed, VS Code installed, VS Code docker and Remote Explorer extensions installed.
@@ -90,5 +90,5 @@ There is a Dockerfile associated with this project. Pre-reqs
 If you wish to copy any files (eg the built HTML files) back to your local machine to check them, use
 
 ```bash
-docker cp CONTAINER:app/_build/html/ temp_dir/
+docker cp CONTAINER:app/_book/ temp_dir/
 ```

_quarto.yml

@@ -0,0 +1,94 @@
+project:
+  type: book
+  output-dir: _book
+
+book:
+  title: "Python for Data Science"
+  author: "The Py4DS Community"
+  favicon: favicon.ico
+  cover-image: logo.png
+  repo-url: https://github.com/aeturrell/python4DS
+  repo-branch: main
+  repo-actions: [edit, issue]
+  google-analytics: "G-LXJC37BJVX"
+  sidebar:
+    style: docked
+    collapse-level: 1
+  chapters:
+    - index.md
+    - part: "Introduction"
+      chapters:
+        - introduction.ipynb
+        - prerequisites.ipynb
+    - part: "Quick Start"
+      chapters:
+        - whole-game.ipynb
+        - data-visualise.ipynb
+        - workflow-basics.ipynb
+        - data-transform.ipynb
+        - workflow-style.ipynb
+        - data-tidy.ipynb
+        - workflow-writing-code.ipynb
+        - data-import.ipynb
+        - workflow-packages-and-environments.qmd
+        - workflow-help.qmd
+    - part: "Visualise"
+      chapters:
+        - visualise.qmd
+        - vis-layers.ipynb
+        - exploratory-data-analysis.ipynb
+        - communicate-plots.ipynb
+    - part: "Transform"
+      chapters:
+        - boolean-data.ipynb
+        - numbers.ipynb
+        - strings.ipynb
+        - regex.ipynb
+        - categorical-data.ipynb
+        - dates-and-times.ipynb
+        - missing-values.ipynb
+        - joins.ipynb
+    - part: "Import"
+      chapters:
+        - spreadsheets.ipynb
+        - databases.ipynb
+        - rectangling.ipynb
+        - webscraping-and-apis.ipynb
+    - part: "Programme"
+      chapters:
+        - functions.ipynb
+        - iteration.ipynb
+        - command-line.md
+    - part: "Communicate"
+      chapters:
+        - markdown.md
+        - quarto.qmd
+  appendices:
+    - references.md
+
+bibliography: references.bib
+search: true
+twitter-card: true
+
+format:
+  html:
+    theme:
+      light: flatly
+      dark: superhero
+    toc: true
+    toc-depth: 3
+    toc-expand: false
+    html-math-method: katex
+    code-copy: true
+    code-link: true
+    code-overflow: wrap
+    number-sections: false
+    include-in-header:
+      - text: |
+          <script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
+
+execute:
+  freeze: auto
+  error: false
+
+jupyter: python3