Build website that demonstrates model computations (#25)

* DOC: create HTML pages from Markdown documents

* DX: activate format-on-save
* DX: add Ruff as Python linter and formatter
* DX: add pre-commit hooks for Python
* MAINT: move markdown files to `docs/` directory

* DOC: host documentation on GitHub

* FIX: install Julia with `juliaup`

* DOC: add example notebooks for Python and Julia

* DX: define `doclive` job

* DOC: import Julia example

https://github.com/mmikhasenko/ThreeBodyDecaysIO.jl/blob/d12b999/builders/Lc2pKpi_read.jl

* DOC: shorten titles
* DOC: remove environment activation cell

* DX: cache Julia and `jupyter-cache` caches

* DOC: show output of package installation

* TEMP: print whether kernel is alive

* DX: switch to Quarto as builder

* MAINT: switch to `pixi.toml` file

* DOC: add links to homepage and repo

* FIX: cache correct `.jupyter_cache` paths

* FIX: set output path to `docs/_build/html`

* DX: activate html preview extension

* FIX: import model from mmikhasenko/ThreeBodyDecaysIO.jl@d12b999

* DOC: improve code rendering

* MAINT: move models to `models/`

* DOC: remove hard-coded JSON example

* DX: hide `pixi.lock` from VSCode search

* FIX: use correct syntax for Python minimum version

* DOC: add dark mode

* FIX: remove format-on-save for notebooks

* DOC: improve print statement

* FIX: remove redundant pre-commit hooks

* DOC: add links to GitHub

* DX: rename Documentation job

Looks better in the Actions overview

* FIX: update links to `models/`

* add text to the Lc2pKpi page

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add new julia deps

* MAINT: update `pixi.lock`

---------

Co-authored-by: Mikhail Mikhasenko <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Documentation
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Julia cache
+        uses: actions/cache@v4
+        with:
+          key: |
+            julia-${{hashFiles('Manifest.toml')}}-${{hashFiles('**/*.jl')}}
+          restore-keys: |
+            julia-${{hashFiles('Manifest.toml')}}
+            julia
+          path: |
+            ~/.julia/
+      - uses: prefix-dev/[email protected]
+        with:
+          cache: true
+      - name: Jupyter cache
+        uses: actions/cache@v4
+        with:
+          key: |
+            jupyter-cache-${{hashFiles('pixi.lock')}}-${{hashFiles('docs/*/*.md')}}
+          restore-keys: |
+            jupyter-cache-${{hashFiles('pixi.lock')}}
+            jupyter-cache
+          path: |
+            **/.jupyter_cache
+      - run: pixi run doc
+      - if: always()
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: >-
+      github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,5 @@
 *.egg-info/
+.ipynb_checkpoints/
 .pixi/
+_build/
 node_modules/

.pre-commit-config.yaml

@@ -14,6 +14,7 @@ repos:
       - id: check-case-conflict
       - id: check-json
       - id: check-merge-conflict
+      - id: check-toml
       - id: check-yaml
       - id: end-of-file-fixer
       - id: mixed-line-ending
@@ -35,3 +36,4 @@ repos:
       - id: toml-sort
         args:
           - --in-place
+        exclude: (?x)^(.*/Manifest\.toml|.*/Project\.toml)$

.taplo.toml

@@ -1,3 +1,9 @@
+exclude = [
+    "**/Manifest.toml",
+    "**/Project.toml",
+    ".pixi/**",
+]
+
 [formatting]
 align_comments = false
 align_entries = false

.vscode/extensions.json

@@ -6,6 +6,9 @@
     "github.vscode-pull-request-github",
     "julialang.language-julia",
     "ms-python.python",
+    "ms-toolsai.jupyter",
+    "ms-vscode.live-server",
+    "quarto.quarto",
     "tamasfe.even-better-toml",
     "yzhang.markdown-all-in-one"
   ]

.vscode/settings.json

@@ -8,7 +8,18 @@
   "[markdown]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
   "editor.formatOnSave": true,
   "julia.executablePath": "${workspaceFolder}/.pixi/envs/default/bin/julia",
-  "python.defaultInterpreterPath": ".pixi/envs/default/bin/python"
+  "livePreview.defaultPreviewPath": "docs/_build/html",
+  "python.defaultInterpreterPath": ".pixi/envs/default/bin/python",
+  "quarto.path": ".pixi/envs/default/bin/quarto",
+  "search.exclude": {
+    "**/*.code-search": true,
+    "**/bower_components": true,
+    "**/node_modules": true,
+    "**/pixi.lock": true
+  }
 }