add a navigation panel to the documentation (#178)

* remove optional .md files

* various updates on tutorials

* reorganize the documentation layout

* add descriptions

.github/workflows/docs.yml

@@ -26,7 +26,7 @@ jobs:
         run: |
           sudo apt-get install graphviz
           pip install -r requirements-docs.txt
-          sphinx-build -j 2 -T -b html docs/source docs/build/html
+          sphinx-build -j 4 -T -b html docs/source docs/build/html
 
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@v4

docs/source/conf.py

@@ -51,6 +51,12 @@
 
 panels_add_bootstrap_css = False
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "jax": ("https://jax.readthedocs.io/en/latest", None),
+}
+
 # Generate the API documentation when building
 autosummary_generate = True
 numpydoc_show_class_members = False
@@ -65,16 +71,16 @@
 plot_html_show_formats = False
 plot_html_show_source_link = False
 
-source_suffix = ['.rst', '.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'myst-nb',
+    '.ipynb': 'myst-nb',
+    '.myst': 'myst-nb',
+}
 
 # The master toctree document.
 master_doc = "index"
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["notebooks/*.ipynb"]
-
 # -- Options for HTML output -------------------------------------------------
 
 html_logo = "images/logo_small.svg"
@@ -105,13 +111,13 @@
     "logo": {
         "text": "pyhgf",
     },
+    "show_nav_level": 2
 }
 
 myst_enable_extensions = ["dollarmath", "colon_fence"]
 
 html_sidebars = {
   "api": [],
   "cite": [],
-  "learn": [],
   "references": [],
 }

docs/source/learn.md

@@ -1,3 +1,50 @@
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Theory
+
+notebooks/0.1-Creating_networks.ipynb
+notebooks/0.2-Theory.ipynb
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: The Hierarchical Gaussian Filter
+
+notebooks/1.1-Binary_HGF.ipynb
+notebooks/1.2-Categorical_HGF.ipynb
+notebooks/1.3-Continuous_HGF.ipynb
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Tutorials
+
+notebooks/2-Using_custom_response_functions.ipynb
+notebooks/3-Multilevel_HGF.ipynb
+notebooks/4-Parameter_recovery.ipynb
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Use cases
+
+notebooks/Example_1_Heart_rate_variability.ipynb
+notebooks/Example_2_Input_node_volatility_coupling.ipynb
+notebooks/Example_3_Multi_armed_bandit.ipynb
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Exercises
+
+notebooks/Exercise_1_Using_the_HGF.ipynb
+```
+
 # Learn
 
 In this section, you can find tutorial notebooks that describe the internals of pyhgf, the theory behind the Hierarchical Gaussian filter, and step-by-step application and use cases of the model. At the beginning of every tutorial, you will find a badge [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ilabcode/pyhgf/blob/master/docs/source/notebooks/0.1-Creating_networks.ipynb) to run the notebook interactively in a Google Colab session.
@@ -27,7 +74,7 @@ How the generative model of the Hierarchical Gaussian filter can be turned into
 ::::
 
 
-## Tutorials
+## The Hierarchical Gaussian Filter
 
 ::::{grid} 3
 
@@ -45,7 +92,7 @@ Introducing with example the binary Hierarchical Gaussian filter and its applica
 :link-type: ref
 :img-top: ./images/categorical.png
 
-The categorical Hierarchical Gaussian Filter as a generalisation of the binary version.
+The categorical Hierarchical Gaussian Filter is a generalisation of the binary HGF to handle categorical distribution with and without transition probabilities.
 
 :::
 
@@ -57,11 +104,12 @@ The categorical Hierarchical Gaussian Filter as a generalisation of the binary v
 
 Introducing with example the continuous Hierarchical Gaussian filter and its applications to signal processing.
 
-+++
-
 :::
 ::::
 
+## Tutorials
+
+Advanced customisation of predictive coding neural networks and Bayesian modelling for group studies. 
 
 ::::{grid} 3
 
@@ -78,6 +126,7 @@ How to adapt any model to specific behaviours and experimental design by using c
 :::{grid-item-card}  Embedding the Hierarchical Gaussian Filter in a Bayesian network for multilevel inference
 :link: multilevel_hgf
 :link-type: ref
+:img-top: ./images/multilevel-hgf.png
 
 
 How to use any model as a distribution to perform hierarchical inference at the group level.
@@ -96,26 +145,34 @@ Recovering parameters from the generative model and using the sampling functiona
 
 ## Use cases
 
+Examples of possible applications and extensions of the standards Hierarchical Gaussian Filters to more complex experimental designs
+
 ::::{grid} 3
 
-:::{grid-item-card}  Bayesian filtering of cardiac dynamics
+:::{grid-item-card}  Inferring cardiac beliefs using Bayesian filtering
 :link: example_1
 :link-type: ref
 
+Application of continuous Bayesian filtering to cardiac physiological recordings to infer interoceptive beliefs and their volatility.
+
 :::
 
 :::{grid-item-card}  Value and volatility coupling with an input node
 :link: example_2
 :link-type: ref
 :img-top: ./images/input_mean_precision.png
 
+Dynamic inference over both the mean and variance of a normal distribution.
+
 :::
 
 :::{grid-item-card}  Multi-armed bandit task with independent reward and punishments
 :link: example_3
 :link-type: ref
 :img-top: ./images/multiarmedbandittask.png
 
+A generalisation of the binary Hierarchical Gaussian Filter to multiarmed bandit where the probabilities of the outcomes are evolving independently.
+
 :::
 ::::
 
@@ -130,5 +187,7 @@ Hand-on exercises to build intuition around the main components of the HGF and u
 :link: hgf_exercises
 :link-type: ref
 
+In-depth introduction to the Hierarchical Gaussian Filter for computational psychiatry (Computational Psychiatry Course, Zurich). About 4 hours. 
+
 :::
 ::::

docs/source/notebooks/0.1-Creating_networks.ipynb

@@ -1854,9 +1854,6 @@
   }
  ],
  "metadata": {
-  "jupytext": {
-   "formats": "ipynb,md:myst"
-  },
   "kernelspec": {
    "display_name": "Python 3 (ipykernel)",
    "language": "python",
@@ -1872,7 +1869,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.16"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,