Improvements to docs infrastructure (TuringLang#497)

* Gitignore Python venv and other temporary files

* Fix typo in versions.sh script

* Use single Project.toml for entire repo

* Include Manifest hashes in GHA cache key

Closes TuringLang#496

* Fix caching in PR preview workflow as well

* Generate Manifest.toml before hashing it

* Add temp workflow to regenerate docs for TuringLang#497

* Revert "Add temp workflow to regenerate docs for TuringLang#497"

This reverts commit d34c745.

* Expand version check script

The action now:

 - runs on all PRs to main / backport branches
 - runs on pushes to main / backport branches

It always checks that the version of Turing in Project.toml matches that
in _quarto.yml.

Additionally, if the PR is targeted at main / the push is to the main
branch, it also checks that the version of Turing matches the latest
release on GitHub.

* Don't ignore Manifest, update deps

* Check Manifest file in GHA as well

* Instantiate project environment in publish workflow

* Modify version check action to also suggest updates as a PR

* Add comment at the top of version check workflow

* Separate version check script into its own file

* Don't need --project as the script sets it up

.github/workflows/preview.yml

@@ -22,29 +22,30 @@ jobs:
         with:
           version: '1.10'
 
+      - name: Instantiate Julia environment
+        run: julia --project=. -e 'using Pkg; Pkg.instantiate()'
+
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
 
       - name: Restore cached _freeze folder
-        id: cache-primes-restore
+        id: cache-restore
         uses: actions/cache/restore@v4
         with:
           path: |
             _freeze/
-          key: ${{ runner.os }}-primes-${{ github.run_id }}
-          restore-keys: |
-            ${{ runner.os }}-primes
+          key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
 
       - name: Render Quarto site
         run: quarto render
 
       - name: Save _freeze folder
-        id: cache-primes-save
+        id: cache-save
         uses: actions/cache/save@v4
         with:
           path: |
             _freeze/
-          key: ${{ runner.os }}-primes-${{ github.run_id }}
+          key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
 
       - name: Deploy to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4

.github/workflows/publish.yml

@@ -20,21 +20,22 @@ jobs:
         with:
           version: '1.10'
 
+      - name: Instantiate Julia environment
+        run: julia --project=. -e 'using Pkg; Pkg.instantiate()'
+
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
 
       - name: Install jq
         run: sudo apt-get install jq
 
       - name: Restore cached _freeze folder
-        id: cache-primes-restore
+        id: cache-restore
         uses: actions/cache/restore@v4
         with:
           path: |
             _freeze/
-          key: ${{ runner.os }}-primes-${{ github.run_id }}
-          restore-keys: |
-            ${{ runner.os }}-primes
+          key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
 
       - name: Extract version from _quarto.yml
         id: extract_version
@@ -70,12 +71,12 @@ jobs:
         run: mv _site/search.json _site/search_original.json
 
       - name: Save _freeze folder
-        id: cache-primes-save
+        id: cache-save
         uses: actions/cache/save@v4
         with:
           path: |
             _freeze/
-          key: ${{ runner.os }}-primes-${{ github.run_id }}
+          key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
 
       - name: Fetch search_original.json from main site
         run: curl -O https://raw.githubusercontent.com/TuringLang/turinglang.github.io/gh-pages/search_original.json

.github/workflows/version_check.jl

@@ -0,0 +1,139 @@
+# Set up a temporary environment just to run this script
+using Pkg
+Pkg.activate(temp=true)
+Pkg.add(["YAML", "TOML", "JSON", "HTTP"])
+import YAML
+import TOML
+import JSON
+import HTTP
+
+PROJECT_TOML_PATH = "Project.toml"
+QUARTO_YML_PATH = "_quarto.yml"
+MANIFEST_TOML_PATH = "Manifest.toml"
+
+function major_minor_match(vs...)
+    first = vs[1]
+    all(v.:major == first.:major && v.:minor == first.:minor for v in vs)
+end
+
+function major_minor_patch_match(vs...)
+    first = vs[1]
+    all(v.:major == first.:major && v.:minor == first.:minor && v.:patch == first.:patch for v in vs)
+end
+
+"""
+Update the version number in Project.toml to match `target_version`.
+
+This uses a naive regex replacement on lines, i.e. sed-like behaviour. Parsing
+the file, editing the TOML and then re-serialising also works and would be more
+correct, but the entries in the output file can end up being scrambled, which
+would lead to unnecessarily large diffs in the PR.
+"""
+function update_project_toml(filename, target_version::VersionNumber)
+    lines = readlines(filename)
+    open(filename, "w") do io
+        for line in lines
+            if occursin(r"^Turing\s*=\s*\"\d+\.\d+\"\s*$", line)
+                println(io, "Turing = \"$(target_version.:major).$(target_version.:minor)\"")
+            else
+                println(io, line)
+            end
+        end
+    end
+end
+
+"""
+Update the version number in _quarto.yml to match `target_version`.
+
+See `update_project_toml` for implementation rationale.
+"""
+function update_quarto_yml(filename, target_version::VersionNumber)
+    # Don't deserialise/serialise as this will scramble lines
+    lines = readlines(filename)
+    open(filename, "w") do io
+        for line in lines
+            m = match(r"^(\s+)- text:\s*\"v\d+\.\d+\"\s*$", line)
+            if m !== nothing
+                println(io, "$(m[1])- text: \"v$(target_version.:major).$(target_version.:minor)\"")
+            else
+                println(io, line)
+            end
+        end
+    end
+end
+
+# Retain the original version number string for error messages, as
+# VersionNumber() will tack on a patch version of 0
+quarto_yaml = YAML.load_file(QUARTO_YML_PATH)
+quarto_version_str = quarto_yaml["website"]["navbar"]["right"][1]["text"]
+quarto_version = VersionNumber(quarto_version_str)
+println("_quarto.yml version: ", quarto_version_str)
+
+project_toml = TOML.parsefile(PROJECT_TOML_PATH)
+project_version_str = project_toml["compat"]["Turing"]
+project_version = VersionNumber(project_version_str)
+println("Project.toml version: ", project_version_str)
+
+manifest_toml = TOML.parsefile(MANIFEST_TOML_PATH)
+manifest_version = VersionNumber(manifest_toml["deps"]["Turing"][1]["version"])
+println("Manifest.toml version: ", manifest_version)
+
+errors = []
+
+if ENV["TARGET_IS_MASTER"] == "true"
+    # This environment variable is set by the GitHub Actions workflow. If it is
+    # true, fetch the latest version from GitHub and update files to match this
+    # version if necessary.
+
+    resp = HTTP.get("https://api.github.com/repos/TuringLang/Turing.jl/releases/latest")
+    latest_version = VersionNumber(JSON.parse(String(resp.body))["tag_name"])
+    println("Latest Turing.jl version: ", latest_version)
+
+    if !major_minor_match(latest_version, project_version)
+        push!(errors, "$(PROJECT_TOML_PATH) out of date")
+        println("$(PROJECT_TOML_PATH) is out of date; updating")
+        update_project_toml(PROJECT_TOML_PATH, latest_version)
+    end
+
+    if !major_minor_match(latest_version, quarto_version)
+        push!(errors, "$(QUARTO_YML_PATH) out of date")
+        println("$(QUARTO_YML_PATH) is out of date; updating")
+        update_quarto_yml(QUARTO_YML_PATH, latest_version)
+    end
+
+    if !major_minor_patch_match(latest_version, manifest_version)
+        push!(errors, "$(MANIFEST_TOML_PATH) out of date")
+        # Attempt to automatically update Manifest
+        println("$(MANIFEST_TOML_PATH) is out of date; updating")
+        old_env = Pkg.project().path
+        Pkg.activate(".")
+        Pkg.update()
+        # Check if versions match now, error if not
+        Pkg.activate(old_env)
+        manifest_toml = TOML.parsefile(MANIFEST_TOML_PATH)
+        manifest_version = VersionNumber(manifest_toml["deps"]["Turing"][1]["version"])
+        if !major_minor_patch_match(latest_version, manifest_version)
+            push!(errors, "Failed to update $(MANIFEST_TOML_PATH) to match latest Turing.jl version")
+        end
+    end
+
+    if isempty(errors)
+        println("All good")
+    else
+        error("The following errors occurred during version checking: \n", join(errors, "\n"))
+    end
+
+else
+    # If this is not true, then we are running on a backport-v* branch, i.e. docs
+    # for a non-latest version. In this case we don't attempt to fetch the latest
+    # patch version from GitHub to check the Manifest (we could, but it is more
+    # work as it would involve paging through the list of releases). Instead,
+    # we just check that the minor versions match.
+    if !major_minor_match(quarto_version, project_version, manifest_version)
+        error("The minor versions of Turing.jl in _quarto.yml, Project.toml, and Manifest.toml are inconsistent:
+              - _quarto.yml: $quarto_version_str
+              - Project.toml: $project_version_str
+              - Manifest.toml: $manifest_version
+              ")
+    end
+end

.github/workflows/version_check.yml

@@ -0,0 +1,74 @@
+# This action checks that the minor versions of Turing.jl specified in the
+# Project.toml, _quarto.yml, and Manifest.toml files are consistent.
+#
+# For pushes to master or PRs to master, it additionally also checks that the
+# version specified in Manifest.toml matches the latest release on GitHub.
+# 
+# If any discrepancies are observed, it will open a PR to fix them.
+
+name: Check Turing.jl version consistency
+on:
+  push:
+    branches:
+      - master
+      - backport-*
+  pull_request:
+    branches:
+      - master
+      - backport-*
+  workflow_dispatch:
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    env:
+      # Determine whether the target branch is master (i.e. this is a push to
+      # master or a PR to master).
+      TARGET_IS_MASTER: ${{ (github.event_name == 'push' && github.ref_name == 'master') || (github.event_name == 'pull_request' && github.base_ref == 'master') }}
+      # Disable precompilation as it takes a long time and is not needed for this workflow
+      JULIA_PKG_PRECOMPILE_AUTO: 0
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@v2
+
+      - name: Log GitHub context variables
+        run: |
+          echo github.event_name: ${{ github.event_name }}
+          echo github.ref_name: ${{ github.ref_name }}
+          echo github.base_ref: ${{ github.base_ref }}
+          echo TARGET_IS_MASTER: ${{ env.TARGET_IS_MASTER }}
+
+      - name: Check version consistency
+        continue-on-error: true
+        run: julia --color=yes .github/workflows/version_check.jl
+
+      - name: Create a PR with suggested changes
+        id: create_pr
+        if: env.TARGET_IS_MASTER
+        uses: peter-evans/create-pull-request@v6
+        with:
+          base: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          branch: update-turing-version/${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          commit-message: "Update Turing.jl version to match latest release"
+          body: "This PR is automatically generated by the `version_check.yml` GitHub Action."
+          title: "Update Turing.jl version to match latest release"
+
+      - name: Comment on PR about suggested changes
+        if: ${{ github.event_name == 'pull_request' && steps.create_pr.outputs.pull-request-operation == 'created' }}
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          message: |
+            Hello! The versions of Turing.jl in your `Project.toml`, `_quarto.yml`, and/or `Manifest.toml` did not match the latest release version found on GitHub (https://github.com/TuringLang/Turing.jl/releases/latest).
+            
+            I've made a PR to update these files to match the latest release: ${{ steps.create_pr.outputs.pull-request-url }}
+
+            Please review the changes and merge the PR if they look good.

.gitignore

@@ -13,12 +13,13 @@
 /tutorials/**/index_files/*
 Testing/
 /*/*/jl_*/
-/Manifest.toml
-/test/Manifest.toml
 .vscode
 _freeze
 _site
 .quarto
 /.quarto/
 changelog.qmd
-versions.qmd
+versions.qmd
+tmp.gif
+.venv
+venv