quarto (#95)

Author: sosiristseng

.github/ci.jl

@@ -8,24 +8,32 @@ using SHA
     using Literate, JSON
 end
 
-# Strip SVG output from a Jupyter notebook
-@everywhere function strip_svg(nbpath)
+# Post-process Jupyter notebook
+@everywhere function postprocess(nbpath)
     oldfilesize = filesize(nbpath)
     nb = open(JSON.parse, nbpath, "r")
     for cell in nb["cells"]
         !haskey(cell, "outputs") && continue
         for output in cell["outputs"]
             !haskey(output, "data") && continue
             datadict = output["data"]
+            ## Remove SVG to reduce file size
             if haskey(datadict, "image/png") || haskey(datadict, "image/jpeg")
                 delete!(datadict, "text/html")
                 delete!(datadict, "image/svg+xml")
             end
+            ## Process LaTeX output, wrap in an array if needed
+            if haskey(datadict, "text/latex")
+                latexcode = datadict["text/latex"]
+                if (! (latexcode isa Vector))
+                    datadict["text/latex"] = [latexcode]
+                end
+            end
         end
     end
     rm(nbpath; force=true)
-    write(nbpath, JSON.json(nb, 1))
-    @info "Stripped SVG in $(nbpath). The original size is $(Base.format_bytes(oldfilesize)). The new size is $(Base.format_bytes(filesize(nbpath)))."
+    write(nbpath, JSON.json(nb, 2))
+    @info "$(nbpath) is processed. The original size is $(Base.format_bytes(oldfilesize)). The new size is $(Base.format_bytes(filesize(nbpath)))."
     return nbpath
 end
 
@@ -41,7 +49,7 @@ function clean_cache(cachedir)
                 if !isfile(nb) && !isfile(lit)
                     cachepath = joinpath(root, fn)
                     @info "Notebook $(nb) or $(lit) not found. Removing $(cachepath) SHA and notebook."
-                    rm(cachepath * ".sha")
+                    rm(cachepath * ".sha"; force=true)
                     rm(cachepath * ".ipynb"; force=true)
                 end
             end
@@ -104,30 +112,30 @@ function list_notebooks(basedir, cachedir)
 end
 
 # Run a Literate notebook
-@everywhere function run_literate(file, cachedir; rmsvg=true)
+@everywhere function run_literate(file, cachedir; dopostproc=true)
     outpath = joinpath(abspath(pwd()), cachedir, dirname(file))
     mkpath(outpath)
     ipynb = Literate.notebook(file, dirname(file); mdstrings=true, execute=true)
-    rmsvg && strip_svg(ipynb)
+    dopostproc && postprocess(ipynb)
     cp(ipynb, joinpath(outpath, basename(ipynb)); force=true)
     return ipynb
 end
 
 function main(;
     basedir=get(ENV, "DOCDIR", "docs"),
     cachedir=get(ENV, "NBCACHE", ".cache"),
-    rmsvg=true)
+    dopostproc=true)
 
     mkpath(cachedir)
     clean_cache(cachedir)
     litnbs = list_notebooks(basedir, cachedir)
 
     if !isempty(litnbs)
-        # Execute literate notebooks in worker process(es)
+        ## Execute literate notebooks in worker process(es)
         ts_lit = pmap(litnbs; on_error=identity) do nb
-            @elapsed run_literate(nb, cachedir; rmsvg)
+            @elapsed run_literate(nb, cachedir; dopostproc)
         end
-        rmprocs(workers()) # Remove worker processes to release some memory
+        rmprocs(workers()) ## Remove worker processes to release some memory
         failed = false
         for (nb, t) in zip(litnbs, ts_lit)
             if t isa ErrorException
@@ -137,9 +145,9 @@ function main(;
         end
 
         if failed
-            error("Please check literate notebook error(s).")
+            error("Please check error(s).")
         else
-            # Print execution result
+            ## Print execution result
             Tables.table([litnbs ts_lit]; header=["Notebook", "Elapsed (s)"]) |> markdown_table(String) |> print
         end
     end

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Build notebooks and publish
 
 on:
   workflow_dispatch:
@@ -39,19 +39,18 @@ jobs:
     - name: Read Julia version
       id: julia-version
       run: python -c 'import tomllib; from pathlib import Path; print("value=", tomllib.loads(Path("Manifest.toml").read_text())["julia_version"], sep="")' >> "$GITHUB_OUTPUT"
-    - name: Get hashes
+    - name: Get environment hash
       id: hash
       run: |
         echo "value=${{ hashFiles('Project.toml', 'Manifest.toml', 'src/**') }}" >> "$GITHUB_OUTPUT"
-        echo "nb=${{ hashFiles('docs/**/*.jl', 'docs/**/*.ipynb') }}" >> "$GITHUB_OUTPUT"
     - name: Cache executed notebooks
       uses: actions/cache@v5
       id: cache-nb
       with:
         path: |
           ${{ env.NBCACHE }}/**/*.ipynb
           ${{ env.NBCACHE }}/**/*.sha
-        key: notebook-${{ steps.hash.outputs.value }}-${{ steps.hash.outputs.nb }}
+        key: notebook-${{ steps.hash.outputs.value }}-${{ hashFiles('docs/**') }}
         restore-keys: |
           notebook-${{ steps.hash.outputs.value }}-
     - name: Setup Julia
@@ -89,31 +88,27 @@ jobs:
       if: ${{ steps.cache-nb.outputs.cache-hit != 'true' }}
       run: julia --project=@. --color=yes -p ${{ env.LITERATE_PROC }} .github/ci.jl
     - name: Copy back built notebooks
-      run: cp --verbose -rf ${{ env.NBCACHE }}/docs/* docs/
-    - name: Setup NodeJS
-      uses: actions/setup-node@v6
-      with:
-        node-version: 'lts/*'
-    - name: Build website
-      env:
-        BASE_URL: /${{ github.event.repository.name }}
       run: |
-        npm install -g "jupyter-book"
-        jupyter-book build --html --strict
+        cp --verbose -rf ${{ env.NBCACHE }}/docs/* docs/
+        find docs/ -type f -name "*.jl" -delete
+    - name: Setup Quarto
+      if: ${{ runner.environment == 'github-hosted' }}
+      uses: quarto-dev/quarto-actions/setup@v2
+    - name: Render Quarto Project
+      run: quarto render docs/
     - name: Upload pages artifact
-      if: ${{ github.ref == 'refs/heads/main' }}
       uses: actions/upload-pages-artifact@v4
+      if: ${{ github.ref == 'refs/heads/main' }}
       with:
-        path: './_build/html'
+        path: docs/_site/
 
-  # Deployment job
   deploy:
-    name: Deploy to GitHub pages and Notebook branch
+    name: Deploy to GitHub pages
     needs: CI
-    if: ${{ github.ref == 'refs/heads/main' }}
+    if: ${{ github.ref == 'refs/heads/main'}}
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:
-      pages: write    # to deploy to Pages
+      pages: write # to deploy to Pages
       id-token: write # to verify the deployment originates from an appropriate source
     environment:
       name: github-pages

.github/workflows/clear-pr-cache.yml

@@ -6,9 +6,9 @@ on:
 
 jobs:
   cleanup:
-    runs-on: ubuntu-slim
     permissions:
       actions: write
+    runs-on: ubuntu-slim
     steps:
       - name: Cleanup
         run: |

.github/workflows/linkcheck.yml

@@ -51,7 +51,7 @@ jobs:
         with:
           fail: false
           failIfEmpty: false
-          args: '--accept 200,204,429 --verbose --no-progress --cache --max-cache-age 1d "docs/**/*.md" "docs/**/*.jl"'
+          args: '--accept 200,204,429 --verbose --no-progress --cache --max-cache-age 1d "docs/**/*.md" "docs/**/*.qmd" "docs/**/*.jl"'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Create Issue From File

docs/.gitignore

@@ -0,0 +1,3 @@
+/.quarto/
+**/*.quarto_ipynb
+*.html.md

docs/_quarto.yml

@@ -0,0 +1,48 @@
+# https://quarto.org/docs/projects/quarto-projects.html
+project:
+  type: website
+  output-dir: _site
+
+# https://quarto.org/docs/websites/
+website:
+  title: CaMKII model
+  page-navigation: true
+  bread-crumbs: true
+  back-to-top-navigation: true
+  reader-mode: true
+  repo-url: https://github.com/ntumitolab/ecme-rirr-dox/
+  site-url: https://ntumitolab.github.io/ecme-rirr-dox/
+  search:
+    show-item-context: true
+    type: overlay
+  # https://quarto.org/docs/websites/website-navigation.html
+  navbar:
+    search: true
+    tools:
+      - icon: github
+        href: https://github.com/ntumitolab/ecme-rirr-dox/
+  sidebar:
+    title: false
+    style: floating
+    collapse-level: 2
+    align: left
+    contents:
+      - index.qmd
+      - auto: "*.ipynb"
+
+# bibliography: references.bib
+
+# https://quarto.org/docs/output-formats/html-basics.html
+format:
+  html:
+    respect-user-color-scheme: true
+    toc: true
+    theme: simplex
+    code-copy: true
+    code-overflow: wrap
+    grid:
+      sidebar-width: 300px
+      body-width: 1000px
+      margin-width: 350px
+    # keep-md: true
+    # css: styles.css