Merge pull request #246 from alan-turing-institute/quarto

Migrate deployment to GitHub Pages

.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+on:
+  push:
+    branches: main
+
+name: Render and publish
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Render Quarto project
+        uses: quarto-dev/quarto-actions/render@v2
+        with:
+          to: html
+        env:
+          # The US election story needs an increased call stack size, not sure why
+          QUARTO_DENO_EXTRA_OPTIONS: --v8-flags=--stack-size=2048
+
+      - name: Upload files to gh-pages branch
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages

.gitignore

@@ -5,3 +5,6 @@
 
 stories/data/
 stories/2022-10-06-Boris-Bikes/routes/*
+/.quarto/
+_site/
+docs/

README.md

@@ -8,7 +8,7 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-31-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-Our stories are published online via fastpages, you can check them out [here](https://alan-turing-institute.github.io/TuringDataStories-fastpages/).
+Our stories are published online using Quarto and GitHub Pages: you can check them out [here](https://alan-turing-institute.github.io/TuringDataStories/).
 Looking for how to get involved? [Click here.](https://github.com/alan-turing-institute/TuringDataStories#contributing)
 
 ### Our vision
@@ -49,19 +49,41 @@ All contributors are asked to follow our [code of conduct](CODE_OF_CONDUCT.md) a
 
 ### How to Read Stories
 
-Our stories are published online via fastpages. You can check them out [here](https://alan-turing-institute.github.io/TuringDataStories-fastpages/).
+Our stories are published online using Quarto and GitHub Pages. You can check them out [here](https://alan-turing-institute.github.io/TuringDataStories/).
 
 Alternatively, click the binder badge at the top of this README to load an interactive version of our stories.
 
-Another option is to run the notebooks locally yourself. To do this, we recommend [installing](https://docs.conda.io/projects/conda/en/latest/user-guide/install/) conda, cloning this repository, and then [setting up an environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file) using
+To build the website locally, install [Quarto](https://quarto.org/) and run from the top-level directory of this repository:
+```bash
+QUARTO_DENO_EXTRA_OPTIONS=--v8-flags=--stack-size=2048 quarto render
 ```
-git clone [email protected]:alan-turing-institute/TuringDataStories.git
-cd TuringDataStories
+Note that Quarto uses precalculated outputs for each notebook cell.
+
+Another option is to run the notebooks locally yourself.
+Some of the notebooks have `requirements.txt` files inside their respective subdirectories; you can set up a virtual environment to run the notebooks using
+
+```bash
+python -m venv tds_venv
+source tds_venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+If this is not present, then you will need to instead use the `binder/environment.yml` file with [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/):
+```bash
 conda env create -f binder/environment.yml
 ```
+
 Any problems, open an issue!
 
 
+### Adding a new story
+
+Under the `stories` directory, create a new folder with the name `YYYY-MM-DD-<Title>` and place your notebook inside there.
+Make sure you have already run all the cells in your notebook.
+That's all!
+
+If your notebook is not ready to be published to the web, you can prefix the folder with an underscore: Quarto will then ignore it.
+
 ### About the project
 
 This project was initially formed by a desire to contribute and advance to the analysis of government COVID-19 data.

_quarto.yml

@@ -0,0 +1,17 @@
+project:
+  type: website
+  output-dir: docs
+  render:
+    - "*.qmd"
+    - "stories/*/*.ipynb"
+    - "!stories/_*"
+website:
+  title: "Turing Data Stories"
+  navbar:
+    right:
+      - icon: github
+        href: https://github.com/alan-turing-institute/turingdatastories
+format:
+  html:
+    theme: cosmo
+    css: styles.css

index.qmd

@@ -0,0 +1,18 @@
+---
+listing:
+  contents: stories 
+  sort: "date desc"
+  type: default
+  categories: true
+  sort-ui: false
+  filter-ui: false
+page-layout: full
+title-block-banner: false
+---
+
+[![](logos/TDS-logo-wide.png){fig-alt="Turing Data Stories Logo"}](https://github.com/alan-turing-institute/TuringDataStories)
+
+An open community creating “Data Stories”: A mix of open data, code, narrative 💬, visuals 📊📈 and knowledge 🧠 to help understand the world around us. 
+Want to contribute? Take a look [here](https://github.com/alan-turing-institute/TuringDataStories#contributing).
+
+# Posts

stories/2021-02-26-US-election/2021-02-26-Modelling-Mail-In-Votes-In-the-2020-US-Election.ipynb

@@ -6,8 +6,19 @@
    "source": [
     "# Modelling Mail-In Votes In the 2020 US Election\n",
     "\n",
-    "- categories: [US Election, Linear regression, Bayesian inference]\n",
+    "> Using hierarchical Bayesian modeling to predict outcomes and associated uncertainties in the 2020 US election.\n",
     "\n",
+    "\n",
+    "- toc: false\n",
+    "- categories: [US Election, Linear regression, Bayesian modeling]\n",
+    "- author: Eric Daub\n",
+    "- image: images/story_previews/2021-02-26-US-Election.png"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "## Author\n",
     "\n",
     "* **Eric Daub**, Alan Turing Institute, GitHub: [@edaub](https://github.com/edaub).\n",
@@ -813,8 +824,8 @@
     "range of outcomes. If $a$ and $b$ are less than 1, then the\n",
     "distribution is biased towards the extreme values of 0 or 1, while if\n",
     "they are greater than 1 then the distribution is biased towards\n",
-    "0.5. If $a > b$, then the model is more biased towards 1, while if $b\n",
-    "> a$ then the model is biased towards 0.  Thus we can specify a huge\n",
+    "0.5. If $a > b$, then the model is more biased towards 1, while if \n",
+    "$b > a$ then the model is biased towards 0. Thus we can specify a huge\n",
     "range of distributions with just two parameters."
    ]
   },