jbook2

.github/.kodiak.toml

@@ -1,9 +1,9 @@
-# https://kodiakhq.com/docs/recipes
-version = 1
-
-[merge]
-  method                               = "squash"
-  block_on_neutral_required_check_runs = true
-  [merge.message]
-    title = "pull_request_title"
-    body  = "pull_request_body"
+# https://kodiakhq.com/docs/recipes
+version = 1
+
+[merge]
+  method                               = "squash"
+  block_on_neutral_required_check_runs = true
+  [merge.message]
+    title = "pull_request_title"
+    body  = "pull_request_body"

.github/ci.jl

@@ -1,23 +1,20 @@
-using IJulia
 using JSON
-using Pkg
+using Literate
+
 ENV["GKSwstype"] = "100"
 
-function main(;
-    basedir=get(ENV, "DOCDIR", "docs"),
-    cachedir=get(ENV, "NBCACHE", ".cache"),
-    rmsvg=true)
-    nb = get(ENV, "NB", "test.ipynb")
-    IJulia.installkernel("Julia", "--project=@.")
-    # nbconvert command options
-    kernelname = "--ExecutePreprocessor.kernel_name=julia-1.$(VERSION.minor)"
-    execute = ifelse(get(ENV, "ALLOWERRORS", "false") == "true", "--execute --allow-errors", "--execute")
-    timeout = "--ExecutePreprocessor.timeout=" * get(ENV, "TIMEOUT", "-1")
-    nbout = joinpath(abspath(pwd()), cachedir, nb)
-    mkpath(dirname(nbout))
-    cmd = `jupyter nbconvert --to notebook $(execute) $(timeout) $(kernelname) --output $(nbout) $(nb)`
-    run(cmd)
-    rmsvg && strip_svg(nbout)
+function main(; rmsvg=true)
+    file = get(ENV, "NB", "test.ipynb")
+    cachedir = get(ENV, "NBCACHE", ".cache")
+    nb = if endswith(file, ".jl")
+        run_literate(file; cachedir)
+    elseif endswith(file, ".ipynb")
+        lit = to_literate(file)
+        run_literate(lit; cachedir)
+    else
+        error("$(file) is not a valid notebook file!")
+    end
+    rmsvg && strip_svg(nb)
     return nothing
 end
 
@@ -42,4 +39,35 @@ function strip_svg(ipynb)
     return ipynb
 end
 
+# Convert a Jupyter notebook into a Literate notebook. Adapted from https://github.com/JuliaInterop/NBInclude.jl.
+function to_literate(nbpath; shell_or_help = r"^\s*[;?]")
+    nb = open(JSON.parse, nbpath, "r")
+    jlpath = splitext(nbpath)[1] * ".jl"
+    open(jlpath, "w") do io
+        separator = ""
+        for cell in nb["cells"]
+            if cell["cell_type"] == "code"
+                s = join(cell["source"])
+                isempty(strip(s)) && continue # Jupyter doesn't number empty cells
+                occursin(shell_or_help, s) && continue  # Skip cells with shell and help commands
+                print(io, separator, "#---\n", s)  # Literate code block mark
+                separator = "\n\n"
+            elseif cell["cell_type"] == "markdown"
+                txt = join(cell["source"])
+                print(io, separator, "#===\n", txt, "\n===#")
+                separator = "\n\n"
+            end
+        end
+    end
+    return jlpath
+end
+
+function run_literate(file; cachedir = ".cache")
+    outpath = joinpath(abspath(pwd()), cachedir, dirname(file))
+    mkpath(outpath)
+    ipynb = Literate.notebook(file, dirname(file); mdstrings=true, execute=true)
+    cp(ipynb, joinpath(outpath, basename(ipynb)); force=true)
+    return ipynb
+end
+
 main()

.github/workflows/automerge.yml

@@ -1,23 +1,23 @@
-# A variant of https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions
-name: Dependabot auto-merge
-on: pull_request
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  dependabot:
-    runs-on: ubuntu-slim
-    if: github.event.pull_request.user.login == 'dependabot[bot]'
-    steps:
-      - name: Dependabot metadata
-        id: metadata
-        uses: dependabot/fetch-metadata@v2
-        with:
-          github-token: "${{ secrets.GITHUB_TOKEN }}"
-      - name: Enable auto-merge for Dependabot PRs
-        run: gh pr edit "$PR_URL" --add-label "automerge"
-        env:
-          PR_URL: ${{ github.event.pull_request.html_url }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# A variant of https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions
+name: Dependabot auto-merge
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-slim
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+      - name: Enable auto-merge for Dependabot PRs
+        run: gh pr edit "$PR_URL" --add-label "automerge"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -12,15 +12,13 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  NBCACHE: ".cache"
+  JULIA_CI: 'true'
   JULIA_CONDAPKG_BACKEND: 'Null'
   JULIA_CONDAPKG_OFFLINE: 'true'
   JULIA_CPU_TARGET: 'generic;icelake-server,clone_all;znver3,clone_all'
-  JULIA_CI: 'true'
   JULIA_NUM_THREADS: 'auto'
-  TIMEOUT: '600'
-  ALLOWERRORS: 'false'
-  PY_VER: '3.13'
+  NBCACHE: '.cache'
+  PY_VER: '3.14'
 
 jobs:
   setup:
@@ -65,19 +63,17 @@ jobs:
         arch: ${{ runner.arch }}
     - name: Install Julia packages
       if: ${{ steps.cache-julia.outputs.cache-hit != 'true' }}
-      shell: julia --color=yes {0}
+      shell: julia --color=yes --project=@. {0}
       run: |
         using Pkg, Dates
-        Pkg.add(["IJulia", "JSON"])
-        Pkg.activate(".")
         Pkg.instantiate()
         Pkg.precompile()
         if ENV["RUNNER_ENVIRONMENT"] == "github-hosted"
             Pkg.gc(;collect_delay=Day(0))
         end
     - name: List notebooks as a JSON array
       id: set-matrix
-      run: echo "matrix=$(python -c 'import glob, json; print(json.dumps(glob.glob("**/*.ipynb", root_dir="docs", recursive=True)))')" >> "$GITHUB_OUTPUT"
+      run: echo "matrix=$(python -c 'import glob, json; print(json.dumps(glob.glob("**/*.ipynb", root_dir="docs", recursive=True) + glob.glob("**/*.jl", root_dir="docs", recursive=True)))')" >> "$GITHUB_OUTPUT"
 
   execute:
     needs: setup
@@ -116,6 +112,7 @@ jobs:
         with:
           version: ${{ needs.setup.outputs.ver }}
           arch: ${{ runner.arch }}
+          show-versioninfo: 'true'
       - name: Restore Julia packages
         uses: actions/cache/restore@v5
         if: ${{ steps.nb-cache.outputs.cache-hit != 'true' }}
@@ -150,15 +147,24 @@ jobs:
           merge-multiple: true
       - name: Copy back built notebooks
         run: cp --verbose -rf ${{ env.NBCACHE }}/docs/* docs/
-      - name: Setup Quarto
-        uses: quarto-dev/quarto-actions/setup@v2
-      - name: Render Quarto Project
-        run: quarto render docs --to html
-      - name: Upload artifact for GH pages
-        uses: actions/upload-pages-artifact@v4
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        id: setup-python
+        with:
+          python-version: ${{ env.PY_VER }}
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install Python dependencies
+        run: uv pip install --system -r requirements.txt
+      - name: Build website
+        env:
+          BASE_URL: /${{ github.event.repository.name }}
+        run: jupyter-book build --html
+      - name: Upload pages artifact
         if: ${{ github.ref == 'refs/heads/main' }}
+        uses: actions/upload-pages-artifact@v4
         with:
-          path: docs/_site/
+          path: './_build/html'
 
   # CI conclusion for GitHub status check
   # Adaped from https://brunoscheufler.com/blog/2022-04-09-the-required-github-status-check-that-wasnt
@@ -178,7 +184,7 @@ jobs:
 
   # Deployment job
   deploy:
-    name: Deploy to GitHub pages
+    name: Deploy to GitHub pages and Notebook branch
     needs: render
     if: ${{ github.ref == 'refs/heads/main' }}
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment

.github/workflows/linkcheck.yml

@@ -16,23 +16,27 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  PY_VER: '3.14'
+
 jobs:
   linkcheck:
-    env:
-      DIR: 'docs'
     runs-on: ubuntu-latest
+    permissions:
+      issues: write # required for peter-evans/create-issue-from-file
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@v6
+        id: setup-python
         with:
-          python-version: '3.x'
-      - name: Install requirements
+          python-version: ${{ env.PY_VER }}
+      - name: Install nbconvert
         run: pip install nbconvert
       - name: Convert ipynb files to markdown
         run: >
-          find ${{ env.DIR }} -type f -name '*.ipynb' |
+          find docs/ -type f -name '*.ipynb' |
           parallel jupyter nbconvert --to markdown {}
       - name: Restore lychee cache
         id: restore-cache
@@ -41,13 +45,13 @@ jobs:
           path: .lycheecache
           key: cache-lychee-${{ github.sha }}
           restore-keys: cache-lychee-
-      - name: Lychee link check
-        uses: lycheeverse/lychee-action@v2.7.0
+      - name: Lychee Checker
+        uses: lycheeverse/lychee-action@v2
         id: lychee
         with:
           fail: false
           failIfEmpty: false
-          args: --accept 200,204,429 --verbose --no-progress --cache --max-cache-age 1d "${{ env.DIR }}/**/*.md" "${{ env.DIR }}/**/*.qmd" "${{ env.DIR }}/**/*.jl"
+          args: '--accept 200,204,429 --verbose --no-progress --cache --max-cache-age 1d "docs/**/*.md" "docs/**/*.jl"'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Create Issue From File

.github/workflows/update-manifest.yml

@@ -30,6 +30,7 @@ jobs:
         uses: julia-actions/setup-julia@v2
         with:
           version: '1'
+          arch: ${{ runner.arch }}
       - name: Update Julia dependencies
         env:
           JULIA_PKG_PRECOMPILE_AUTO: '0'

Manifest.toml

@@ -2,7 +2,7 @@
 
 julia_version = "1.12.3"
 manifest_format = "2.0"
-project_hash = "dd841a67f83de9192b83c10324ed0dda966dd0dd"
+project_hash = "fef8182752b68577debb0fe3f26aacaa85f7dbfb"
 
 [[deps.ADTypes]]
 git-tree-sha1 = "8b2b045b22740e4be20654175cc38291d48539db"
@@ -868,6 +868,12 @@ git-tree-sha1 = "68c173f4f449de5b438ee67ed0c9c748dc31a2ec"
 uuid = "34004b35-14d8-5ef3-9330-4cdb6864b03a"
 version = "0.3.28"
 
+[[deps.IOCapture]]
+deps = ["Logging", "Random"]
+git-tree-sha1 = "0ee181ec08df7d7c911901ea38baf16f755114dc"
+uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
+version = "1.0.0"
+
 [[deps.IfElse]]
 git-tree-sha1 = "debdd00ffef04665ccbb3e150747a77560e8fad1"
 uuid = "615f187c-cbe4-4ef1-ba3b-2fcf58d6d173"
@@ -1220,6 +1226,12 @@ version = "3.54.0"
     Sparspak = "e56a9233-b9d6-4f03-8d0f-1825330902ac"
     blis_jll = "6136c539-28a5-5bf0-87cc-b183200dce32"
 
+[[deps.Literate]]
+deps = ["Base64", "IOCapture", "JSON", "REPL"]
+git-tree-sha1 = "bb26d8b8ed0fa451ce3511e99c950653a2f31fe1"
+uuid = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+version = "2.21.0"
+
 [[deps.LogExpFunctions]]
 deps = ["DocStringExtensions", "IrrationalConstants", "LinearAlgebra"]
 git-tree-sha1 = "13ca9e2586b89836fd20cccf56e57e2b9ae7f38f"

Project.toml

@@ -7,8 +7,10 @@ authors = ["Wen-Wei Tseng <sosiristseng@gmail.com>"]
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
 DisplayAs = "0b91fe84-8a4c-11e9-3e1d-67c38462b6d6"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 NaNMath = "77ba4419-2d1f-58cd-9bb1-8ffee604a2e3"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
@@ -20,5 +22,7 @@ Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 
 [compat]
 ForwardDiff = "1"
+JSON = "1.3.0"
 Latexify = "0.16"
+Literate = "2.21.0"
 ModelingToolkit = "10"