Move cookbooks out from under quarto, into docs directory. (#1483)

This PR:

- renames
  - `some_oddities` => `jax_basics`
  - `methods_of_generative_fun` => `generative_function_interface`, 
  - `choicemap_creation_selection` => `choicemaps`
  - moves all notebooks into `docs`, so they can built by mkdocs-jupyter

---------

Co-authored-by: Sam Ritchie <[email protected]>

Author: femtomc

.github/workflows/docs.yml

@@ -29,11 +29,6 @@ jobs:
             ${{ secrets.INSIDER_SSH_KEY }}
             ${{ secrets.MKDOCSTRINGS_PYTHON_SSH_KEY }}
 
-      - name: Set up Quarto
-        uses: quarto-dev/quarto-actions/setup@v2
-        with:
-          version: 1.4.553
-
       - uses: actions/setup-python@v4
         with:
           python-version: 3.11.5

.github/workflows/notebooks.yml

@@ -28,9 +28,6 @@ jobs:
             ${{ secrets.MKDOCSTRINGS_PYTHON_SSH_KEY }}
             ${{ secrets.INSIDER_SSH_KEY }}
 
-      - name: Set up Quarto
-        uses: quarto-dev/quarto-actions/setup@v2
-
       - uses: actions/setup-python@v4
         with:
           python-version: 3.11.5

.github/workflows/test_docs.yml

@@ -1,17 +1,14 @@
 {
  "cells": [
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
     "vscode": {
      "languageId": "raw"
     }
    },
    "source": [
-    "---\n",
-    "title: Choice maps\n",
-    "subtitle: What's a choice map, and how do I create one or select from it?\n",
-    "---"
+    "# Choice maps"
    ]
   },
   {
@@ -651,7 +648,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -665,7 +662,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

notebooks/cookbook/basics/choicemap_creation_selection.ipynb renamed to docs/cookbook/active/choice_maps.ipynb

@@ -1,13 +1,10 @@
 {
  "cells": [
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "---\n",
-    "title: Methods of generative functions\n",
-    "subtitle: Ok I have a generative function... now what can I do with it?\n",
-    "--- "
+    "# The generative function interface"
    ]
   },
   {
@@ -421,7 +418,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

notebooks/cookbook/basics/debugging.ipynb renamed to docs/cookbook/active/debugging.ipynb

@@ -1,17 +1,14 @@
 {
  "cells": [
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {
     "vscode": {
      "languageId": "raw"
     }
    },
    "source": [
-    "---\n",
-    "title: Introduction\n",
-    "subtitle: Morning coffee & first steps from the probabilistic base camp.\n",
-    "---"
+    "# Introduction"
    ]
   },
   {
@@ -465,7 +462,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

notebooks/cookbook/basics/methods_of_generative_fun.ipynb renamed to docs/cookbook/active/generative_function_interface.ipynb

@@ -1,13 +1,10 @@
 {
  "cells": [
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "---\n",
-    "title: Some oddities\n",
-    "subtitle: What are some sharp edges of Jax that are good to know before really starting?\n",
-    "---"
+    "# JAX Basics"
    ]
   },
   {
@@ -619,7 +616,7 @@
    "outputs": [],
    "source": [
     "genjax.truncated_normal.sample(\n",
-    "    jax.random.PRNGKey(2), 0.5382424, 0.05, 0.83921564 - 0.03, 0.83921564 + 0.03\n",
+    "    jax.random.key(2), 0.5382424, 0.05, 0.83921564 - 0.03, 0.83921564 + 0.03\n",
     ")\n",
     "\n",
     "minv = 0.83921564 - 0.03\n",
@@ -634,17 +631,17 @@
     "    return std * jax.random.truncated_normal(key, low, high, (), jnp.float32) + mean\n",
     "\n",
     "\n",
-    "raw_jax_truncated(jax.random.PRNGKey(2), minv, maxv, mean, std)\n",
+    "raw_jax_truncated(jax.random.key(2), minv, maxv, mean, std)\n",
     "# ==> Array(0.80921566, dtype=float32)\n",
     "\n",
-    "jax.jit(raw_jax_truncated)(jax.random.PRNGKey(2), minv, maxv, mean, std)\n",
+    "jax.jit(raw_jax_truncated)(jax.random.key(2), minv, maxv, mean, std)\n",
     "# ==> Array(nan, dtype=float32)"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -658,9 +655,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

notebooks/active/intro.ipynb renamed to docs/cookbook/active/intro.ipynb

@@ -10,7 +10,6 @@ This project uses:
 - [poetry](https://python-poetry.org/) for dependency management
 - [nox](https://nox.thea.codes/en/stable/) to automate testing/linting/building.
 - [mkdocs](https://www.mkdocs.org/) to generate static documentation.
-- [quarto](https://quarto.org/) to render Jupyter notebooks for tutorial notebooks.
 
 ### Commit Hooks
 
@@ -122,10 +121,6 @@ version of `jax` and `jaxlib` resolve with the versions of packages in the
 
 ### Documentation environment setup
 
-If you want to deploy the documentation and Jupyter notebooks to static HTML,
-you'll need to install [quarto](https://quarto.org/docs/get-started/) on your
-machine.
-
 GenJAX builds documentation using an insiders-only version of
 [mkdocs-material](https://squidfunk.github.io/mkdocs-material/). GenJAX will
 attempt to fetch this repository during the documentation build step.
@@ -136,8 +131,7 @@ Run the following command to fully build the documentation:
 nox -r -s docs-build
 ```
 
-This command will use `mkdocs` to build the static site, and then use `quarto`
-to render the notebooks into the static site directory.
+This command will use `mkdocs` to build the static site.
 
 To view the generated site, run:
 
@@ -151,21 +145,6 @@ or to run both commands in sequence:
 nox -r -s docs-build-serve
 ```
 
-## Granting someone access to GenJAX's Artifact Registry
-
-- Visit the [artifact registry
-  page](https://console.cloud.google.com/artifacts?hl=en&project=probcomp-caliban)
-  and click the checkbox next to `probcomp` to bring up the "Permissions" tab on
-  the right side of the page
-- Click "Add Principal"
-- Under "New principals", type in the email addresses (associated with a Google
-  account) of the people you want to grant access
-- Under "Role", fill in "Artifact Registry Reader"
-- Click "Save"
-
-These users should now be able to follow the README.md instructions to install
-GenJAX.
-
 ## Releasing GenJAX
 
 Published GenJAX artifacts live [on PyPI](https://pypi.org/project/genjax/) and

notebooks/cookbook/basics/some_oddities.ipynb renamed to docs/cookbook/active/jax_basics.ipynb

@@ -21,13 +21,42 @@ copyright: Copyright © 2023 MIT Probabilistic Computing Project
 
 nav:
   - Home: index.md
-  - Cookbook: cookbook/index.md
+  - Cookbook:
+      - Just starting out:
+          - JAX basics: cookbook/active/jax_basics.ipynb
+          - Introduction: cookbook/active/intro.ipynb
+          - The generative function interface: cookbook/active/generative_function_interface.ipynb
+          - Working with choice maps: cookbook/active/choice_maps.ipynb
+          - Debugging: cookbook/active/debugging.ipynb
+
+      - Still being tidied:
+          - Generative functions: cookbook/inactive/generative_fun.ipynb
+
+          - Expressivity:
+              - cookbook/inactive/expressivity/conditionals.ipynb
+              - cookbook/inactive/expressivity/iterating_computation.ipynb
+              - cookbook/inactive/expressivity/masking.ipynb
+              - cookbook/inactive/expressivity/mixture.ipynb
+              - cookbook/inactive/expressivity/custom_distribution.ipynb
+              - cookbook/inactive/expressivity/stochastic_probabilities.ipynb
+              - cookbook/inactive/expressivity/stochastic_probabilities_math.ipynb
+
+          - Inference:
+              - Importance sampling: cookbook/inactive/inference/importance_sampling.ipynb
+              - Custom proposal: cookbook/inactive/inference/custom_proposal.ipynb
+              - MCMC: cookbook/inactive/inference/mcmc.ipynb
+
+          - Differentiation:
+              - ADEV Example: cookbook/inactive/differentiation/adev_example.py
+
+          - Library developers:
+              - Dimap combinator: cookbook/inactive/library_author/dimap_combinator.ipynb
+
   - Library reference:
       - Core: library/core.md
       - Generative functions: library/generative_functions.md
       - Combinators: library/combinators.md
       - Inference: library/inference.md
-    # - ADEV: library/adev.md
   - For developers:
       - Developing: developing.md
       - Code of conduct: codeofconduct.md
@@ -38,6 +67,9 @@ theme:
   name: material
   logo: assets/img/small_logo.png
   favicon: assets/img/gen-logo.png
+  font:
+      text: Roboto
+      code: Berkeley Mono
   icon:
     repo: fontawesome/brands/github
   features:
@@ -77,6 +109,15 @@ plugins:
   - search
   - offline
   - markdown-exec
+  - mkdocs-jupyter:
+        execute: true
+        allow_errors: false
+        ignore:
+         # TODO: re-enable once we can support marginals as targets
+          - "cookbook/inactive/expressivity/ravi_stack.ipynb"
+          - "cookbook/inactive/differentiation/adev_demo.py"
+
+        highlight_extra_classes: "custom-css-classes"
   - typeset:
       enabled: true
   - git-revision-date-localized: