Reorganise user guide section (#578)

* Don't let julia-actions delete cache * Reorganise user guide * Allow different workflows/PRs to share cached Julia environment * Merge _quarto.yml and _metadata.yml * Reorganise tutorials section * Fix colon in title * Fix aliases * Fix more aliases * Tidy up navigation bar
TuringLang · Jan 17, 2025 · 5d70e83 · 5d70e83
1 parent 2190475
commit 5d70e83
Show file tree

Hide file tree

Showing 32 changed files with 123 additions and 109 deletions.
diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
@@ -10,7 +10,6 @@ concurrency:
   group: docs
 
 permissions:
-  actions: write
   contents: write
   pull-requests: write
 
@@ -31,6 +30,9 @@ jobs:
 
       - name: Load Julia packages from cache
         uses: julia-actions/cache@v2
+        with:
+          cache-name: julia-cache;${{ hashFiles('**/Manifest.toml') }}
+          delete-old-caches: false
 
       # Note: needs resolve() to fix #518
       - name: Instantiate Julia environment

diff --git a/_quarto.yml b/_quarto.yml
@@ -20,9 +20,9 @@ website:
     background: "#073c44"
     foreground: "#ffffff"
     left:
-      - href: tutorials/docs-00-getting-started/
+      - href: getting-started/
         text: Get Started
-      - href: tutorials/00-introduction/
+      - href: tutorials/coin-flipping/
         text: Tutorials
       - href: https://turinglang.org/library/
         text: Libraries
@@ -50,52 +50,40 @@ website:
     - text: documentation
       collapse-level: 1
       contents:
-        - section: "Users"
-          # href: tutorials/index.qmd, This page will be added later so keep this line commented
-          contents:
-          - tutorials/docs-00-getting-started/index.qmd
-          - tutorials/docs-12-using-turing-guide/index.qmd
+        - getting-started/index.qmd
+        - core-functionality/index.qmd
 
-          - section: "Usage Tips"
-            collapse-level: 1
-            contents:
-              - tutorials/docs-10-using-turing-autodiff/index.qmd
-              - tutorials/usage-custom-distribution/index.qmd
-              - tutorials/usage-probability-interface/index.qmd
-              - tutorials/usage-modifying-logprob/index.qmd
-              - tutorials/usage-generated-quantities/index.qmd
-              - tutorials/docs-17-mode-estimation/index.qmd
-              - tutorials/docs-13-using-turing-performance-tips/index.qmd
-              - tutorials/docs-15-using-turing-sampler-viz/index.qmd
-              - tutorials/docs-11-using-turing-dynamichmc/index.qmd
-              - tutorials/docs-16-using-turing-external-samplers/index.qmd
-
-          - section: "Tutorials"
-            contents:
-              - tutorials/00-introduction/index.qmd
-              - text: Gaussian Mixture Models
-                href: tutorials/01-gaussian-mixture-model/index.qmd
-              - tutorials/02-logistic-regression/index.qmd
-              - tutorials/03-bayesian-neural-network/index.qmd
-              - text: Hidden Markov Models
-                href: tutorials/04-hidden-markov-model/index.qmd
-              - tutorials/05-linear-regression/index.qmd
-              - text: Infinite Mixture Model
-                href: tutorials/06-infinite-mixture-model/index.qmd
-              - tutorials/07-poisson-regression/index.qmd
-              - text: Multinomial Logistic Regression
-                href: tutorials/08-multinomial-logistic-regression/index.qmd
-              - text: Variational Inference
-                href: tutorials/09-variational-inference/index.qmd
-              - text: "Bayesian Differential Equations"
-                href: tutorials/10-bayesian-differential-equations/index.qmd
-              - text: "Probabilistic PCA"
-                href: tutorials/11-probabilistic-pca/index.qmd
-              - tutorials/13-seasonal-time-series/index.qmd
-              - text: "Introduction to Gaussian Processes"
-                href: tutorials/15-gaussian-processes/index.qmd
-              - text: "Gaussian Process Latent Variable Models"
-                href: tutorials/12-gplvm/index.qmd
+        - section: "Usage Tips"
+          collapse-level: 1
+          contents:
+            - usage/automatic-differentiation/index.qmd
+            - usage/custom-distribution/index.qmd
+            - usage/probability-interface/index.qmd
+            - usage/modifying-logprob/index.qmd
+            - usage/generated-quantities/index.qmd
+            - usage/mode-estimation/index.qmd
+            - usage/performance-tips/index.qmd
+            - usage/sampler-visualisation/index.qmd
+            - usage/dynamichmc/index.qmd
+            - usage/external-samplers/index.qmd
+
+        - section: "Tutorials"
+          contents:
+            - tutorials/coin-flipping/index.qmd
+            - tutorials/gaussian-mixture-models/index.qmd
+            - tutorials/bayesian-logistic-regression/index.qmd
+            - tutorials/bayesian-neural-networks/index.qmd
+            - tutorials/hidden-markov-models/index.qmd
+            - tutorials/bayesian-linear-regression/index.qmd
+            - tutorials/infinite-mixture-models/index.qmd
+            - tutorials/bayesian-poisson-regression/index.qmd
+            - tutorials/multinomial-logistic-regression/index.qmd
+            - tutorials/variational-inference/index.qmd
+            - tutorials/bayesian-differential-equations/index.qmd
+            - tutorials/probabilistic-pca/index.qmd
+            - tutorials/bayesian-time-series-analysis/index.qmd
+            - tutorials/gaussian-processes-introduction/index.qmd
+            - tutorials/gaussian-process-latent-variable-models/index.qmd
 
         - section: "Developers"
           contents:
@@ -144,13 +132,26 @@ format:
       light: cosmo
       dark: [cosmo, theming/theme-dark.scss]
     css: theming/styles.css
-    toc: true
     smooth-scroll: true
-    code-overflow: wrap
     output-block-background: true
-
+    toc: true
+    toc-title: "Table of Contents"
+    code-fold: false
+    code-overflow: scroll
 execute:
+  echo: true
+  output: true
   freeze: auto
+include-in-header:
+  - text: |
+      <style>
+        a {
+          text-decoration: none;
+        }
+        a:hover {
+          text-decoration: underline;
+        }
+      </style>
 
 # These variables can be used in any qmd files, e.g. for links:
 # the [Getting Started page]({{< meta get-started >}})

diff --git a/...ials/docs-12-using-turing-guide/index.qmd → core-functionality/index.qmd b/...ials/docs-12-using-turing-guide/index.qmd → core-functionality/index.qmd
@@ -1,6 +1,8 @@
 ---
 title: "Core Functionality"
 engine: julia
+aliases:
+  - ../tutorials/docs-12-using-turing-guide/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/docs-00-getting-started/index.qmd → getting-started/index.qmd b/tutorials/docs-00-getting-started/index.qmd → getting-started/index.qmd
@@ -2,7 +2,8 @@
 title: Getting Started
 engine: julia
 aliases:
-   - ../../
+  - ../tutorials/docs-00-getting-started/index.html
+  - ../index.html
 ---
 
 ```{julia}

diff --git a/tutorials/_metadata.yml b/tutorials/_metadata.yml
diff --git a/...bayesian-differential-equations/index.qmd → ...bayesian-differential-equations/index.qmd b/...bayesian-differential-equations/index.qmd → ...bayesian-differential-equations/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Bayesian Estimation of Differential Equations
+title: Bayesian Differential Equations
 engine: julia
+aliases:
+ - ../10-bayesian-differential-equations/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/05-linear-regression/index.qmd → ...ials/bayesian-linear-regression/index.qmd b/tutorials/05-linear-regression/index.qmd → ...ials/bayesian-linear-regression/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Linear Regression
+title: Bayesian Linear Regression
 engine: julia
+aliases:
+ - ../05-linear-regression/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/02-logistic-regression/index.qmd → ...ls/bayesian-logistic-regression/index.qmd b/tutorials/02-logistic-regression/index.qmd → ...ls/bayesian-logistic-regression/index.qmd
@@ -1,6 +1,8 @@
 ---
 title: Bayesian Logistic Regression
 engine: julia
+aliases:
+ - ../02-logistic-regression/index.html
 ---
 
 ```{julia}
@@ -271,4 +273,4 @@ end
 
 The above shows that with a threshold of 0.07, we correctly predict a respectable portion of the defaults, and correctly identify most non-defaults. This is fairly sensitive to a choice of threshold, and you may wish to experiment with it.
 
-This tutorial has demonstrated how to use Turing to perform Bayesian logistic regression.
+This tutorial has demonstrated how to use Turing to perform Bayesian logistic regression.
diff --git a/...ials/03-bayesian-neural-network/index.qmd → tutorials/bayesian-neural-networks/index.qmd b/...ials/03-bayesian-neural-network/index.qmd → tutorials/bayesian-neural-networks/index.qmd
@@ -1,6 +1,8 @@
 ---
 title: Bayesian Neural Networks
 engine: julia
+aliases:
+ - ../03-bayesian-neural-network/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/07-poisson-regression/index.qmd → ...als/bayesian-poisson-regression/index.qmd b/tutorials/07-poisson-regression/index.qmd → ...als/bayesian-poisson-regression/index.qmd
@@ -1,6 +1,8 @@
 ---
 title: Bayesian Poisson Regression
 engine: julia
+aliases:
+ - ../07-poisson-regression/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/13-seasonal-time-series/index.qmd → ...s/bayesian-time-series-analysis/index.qmd b/tutorials/13-seasonal-time-series/index.qmd → ...s/bayesian-time-series-analysis/index.qmd
@@ -1,6 +1,8 @@
 ---
 title: Bayesian Time Series Analysis
 engine: julia
+aliases:
+ - ../13-seasonal-time-series/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/00-introduction/index.qmd → tutorials/coin-flipping/index.qmd b/tutorials/00-introduction/index.qmd → tutorials/coin-flipping/index.qmd
@@ -2,7 +2,8 @@
 title: "Introduction: Coin Flipping"
 engine: julia
 aliases: 
-  - ../
+  - ../00-introduction/index.html
+  - ../00-introduction/
 ---
 
 ```{julia}

diff --git a/tutorials/docs-08-using-turing/index.qmd b/tutorials/docs-08-using-turing/index.qmd
diff --git a/tutorials/docs-09-using-turing-advanced/index.qmd b/tutorials/docs-09-using-turing-advanced/index.qmd
diff --git a/...rials/01-gaussian-mixture-model/index.qmd → tutorials/gaussian-mixture-models/index.qmd b/...rials/01-gaussian-mixture-model/index.qmd → tutorials/gaussian-mixture-models/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Unsupervised Learning using Bayesian Mixture Models
+title: Gaussian Mixture Models
 engine: julia
+aliases:
+ - ../01-gaussian-mixture-model/index.html
 ---
 
 ```{julia}
@@ -10,7 +12,7 @@ using Pkg;
 Pkg.instantiate();
 ```
 
-The following tutorial illustrates the use of Turing for clustering data using a Bayesian mixture model.
+The following tutorial illustrates the use of Turing for an unsupervised task, namely, clustering data using a Bayesian mixture model.
 The aim of this task is to infer a latent grouping (hidden structure) from unlabelled data.
 
 ## Synthetic Data

diff --git a/tutorials/12-gplvm/index.qmd → ...-process-latent-variable-models/index.qmd b/tutorials/12-gplvm/index.qmd → ...-process-latent-variable-models/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Gaussian Process Latent Variable Model
+title: Gaussian Process Latent Variable Models
 engine: julia
+aliases:
+ - ../12-gplvm/index.html
 ---
 
 ```{julia}
@@ -231,4 +233,4 @@ let
 end
 ```
 
-Now, the split between the two groups is visible again.
+Now, the split between the two groups is visible again.
diff --git a/tutorials/15-gaussian-processes/index.qmd → ...gaussian-processes-introduction/index.qmd b/tutorials/15-gaussian-processes/index.qmd → ...gaussian-processes-introduction/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Gaussian Processes
+title: "Gaussian Processes: Introduction"
 engine: julia
+aliases:
+ - ../15-gaussian-processes/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/04-hidden-markov-model/index.qmd → tutorials/hidden-markov-models/index.qmd b/tutorials/04-hidden-markov-model/index.qmd → tutorials/hidden-markov-models/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Bayesian Hidden Markov Models
+title: Hidden Markov Models
 engine: julia
+aliases:
+ - ../04-hidden-markov-model/index.html
 ---
 
 ```{julia}

diff --git a/...rials/06-infinite-mixture-model/index.qmd → tutorials/infinite-mixture-models/index.qmd b/...rials/06-infinite-mixture-model/index.qmd → tutorials/infinite-mixture-models/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Probabilistic Modelling using the Infinite Mixture Model
+title: Infinite Mixture Models
 engine: julia
+aliases:
+ - ../06-infinite-mixture-model/index.html
 ---
 
 ```{julia}

diff --git a/...multinomial-logistic-regression/index.qmd → ...multinomial-logistic-regression/index.qmd b/...multinomial-logistic-regression/index.qmd → ...multinomial-logistic-regression/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Bayesian Multinomial Logistic Regression
+title: Multinomial Logistic Regression
 engine: julia
+aliases:
+ - ../08-multinomial-logistic-regression/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/11-probabilistic-pca/index.qmd → tutorials/probabilistic-pca/index.qmd b/tutorials/11-probabilistic-pca/index.qmd → tutorials/probabilistic-pca/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Probabilistic Principal Component Analysis (p-PCA)
+title: Probabilistic PCA
 engine: julia
+aliases:
+ - ../11-probabilistic-pca/index.html
 ---
 
 ```{julia}

diff --git a/tutorials/09-variational-inference/index.qmd → tutorials/variational-inference/index.qmd b/tutorials/09-variational-inference/index.qmd → tutorials/variational-inference/index.qmd
@@ -1,6 +1,8 @@
 ---
-title: Variational inference (VI) in Turing.jl
+title: Variational Inference
 engine: julia
+aliases:
+ - ../09-variational-inference/index.html
 ---
 
 ```{julia}

diff --git a/...s/docs-10-using-turing-autodiff/index.qmd → usage/automatic-differentiation/index.qmd b/...s/docs-10-using-turing-autodiff/index.qmd → usage/automatic-differentiation/index.qmd
@@ -1,6 +1,8 @@
 ---
 title: Automatic Differentiation
 engine: julia
+aliases:
+  - ../../tutorials/docs-10-using-turing-autodiff/index.html
 ---
 
 ```{julia}

diff --git a/...rials/usage-custom-distribution/index.qmd → usage/custom-distribution/index.qmd b/...rials/usage-custom-distribution/index.qmd → usage/custom-distribution/index.qmd
@@ -1,6 +1,9 @@
 ---
 title: Custom Distributions
 engine: julia
+aliases:
+  - ../../tutorials/usage-custom-distribution/index.html
+  - ../../tutorials/docs-09-using-turing-advanced/index.html
 ---
 
 ```{julia}