From 6f1d4dc588cb246ffa749e053751eb539a2c9d59 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 08:08:27 +0000
Subject: [PATCH 01/18] refactor: use nbsphinx as the default execution lib

---
 docs/_contents/pydata.ipynb         | 148 ++++++++++++++++++++++++++++
 docs/conf.py                        |  14 +--
 docs/examples/pydata.md             | 102 -------------------
 docs/examples/subpages/pydata.ipynb | 148 ++++++++++++++++++++++++++++
 pyproject.toml                      |   4 +-
 5 files changed, 300 insertions(+), 116 deletions(-)
 create mode 100644 docs/_contents/pydata.ipynb
 delete mode 100644 docs/examples/pydata.md
 create mode 100644 docs/examples/subpages/pydata.ipynb

diff --git a/docs/_contents/pydata.ipynb b/docs/_contents/pydata.ipynb
new file mode 100644
index 000000000..7282623aa
--- /dev/null
+++ b/docs/_contents/pydata.ipynb
@@ -0,0 +1,148 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# PyData Library Styles\n",
+    "\n",
+    "This theme has built-in support and special styling for several major visualization libraries in the PyData ecosystem.\n",
+    "This ensures that the images and output generated by these libraries looks good for both light and dark modes.\n",
+    "Below are examples of each that we use as a benchmark for reference.\n",
+    "\n",
+    "## Pandas"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import string\n",
+    "\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "rng = np.random.default_rng()\n",
+    "data = rng.standard_normal((100, 26))\n",
+    "df = pd.DataFrame(data, columns=list(string.ascii_lowercase))\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Matplotlib"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "fig, ax = plt.subplots()\n",
+    "ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "rng = np.random.default_rng()\n",
+    "data = rng.standard_normal((3, 100))\n",
+    "fig, ax = plt.subplots()\n",
+    "ax.scatter(data[0], data[1], c=data[2], s=3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plotly\n",
+    "\n",
+    "The HTML below shouldn't display, but it uses RequireJS to make sure that all\n",
+    "works as expected. If the widgets don't show up, RequireJS may be broken."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import plotly.io as pio\n",
+    "import plotly.express as px\n",
+    "import plotly.offline as py\n",
+    "\n",
+    "pio.renderers.default = \"notebook\"\n",
+    "\n",
+    "df = px.data.iris()\n",
+    "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Xarray\n",
+    "\n",
+    "Here we demonstrate `xarray` to ensure that it shows up properly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "data = xr.DataArray(\n",
+    "        np.random.randn(2, 3),\n",
+    "        dims=(\"x\", \"y\"),\n",
+    "        coords={\"x\": [10, 20]}, attrs={\"foo\": \"bar\"}\n",
+    "      )\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ipyleaflet\n",
+    "\n",
+    "`ipyleaflet` is a **Jupyter**/**Leaflet** bridge enabling interactive maps in the Jupyter notebook environment. this demonstrate how you can integrate maps in your documentation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ipyleaflet import Map, basemaps\n",
+    "\n",
+    "# display a map centered on France\n",
+    "m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])\n",
+    "m"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/conf.py b/docs/conf.py
index 77bedc9a2..73d93cbf3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -34,18 +34,17 @@
     "sphinx_design",
     "sphinx_copybutton",
     "autoapi.extension",
-    "_extension.gallery_directive",
     # For extension examples and demos
     "ablog",
     "jupyter_sphinx",
-    "matplotlib.sphinxext.plot_directive",
-    "myst_nb",
     "sphinxcontrib.youtube",
-    # "nbsphinx",  # Uncomment and comment-out MyST-NB for local testing purposes.
+    "nbsphinx",
     "numpydoc",
     "sphinx_togglebutton",
     "jupyterlite_sphinx",
     "sphinx_favicon",
+    # custom extentions
+    "_extension.gallery_directive",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -71,13 +70,6 @@
 # specifying the natural language populates some key tags
 language = "en"
 
-# -- MyST options ------------------------------------------------------------
-
-# This allows us to use ::: to denote directives, useful for admonitions
-myst_enable_extensions = ["colon_fence", "linkify", "substitution"]
-myst_heading_anchors = 2
-myst_substitutions = {"rtd": "[Read the Docs](https://readthedocs.org/)"}
-
 # -- Ablog options -----------------------------------------------------------
 
 blog_path = "examples/blog/index"
diff --git a/docs/examples/pydata.md b/docs/examples/pydata.md
deleted file mode 100644
index e31a90905..000000000
--- a/docs/examples/pydata.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-file_format: mystnb
-kernelspec:
-  name: python3
-  display_name: Python 3
----
-
-% To test this file with nbsphinx we need to convert to ipynb. To do this:
-% - Run this command: jupytext docs/examples/pydata.md --to ipynb
-% - _Temporarily_ delete the pydata.md file
-% - Uncomment `nbsphinx` and comment `myst_nb` in "extensions" in our conf.py file
-% - Build the docs and test that the results look OK
-% - Undo everything in this list to make sure we revert back to the old structure
-
-# PyData Library Styles
-
-This theme has built-in support and special styling for several major visualization libraries in the PyData ecosystem.
-This ensures that the images and output generated by these libraries looks good for both light and dark modes.
-Below are examples of each that we use as a benchmark for reference.
-
-## Pandas
-
-```{code-cell}
-import string
-
-import numpy as np
-import pandas as pd
-
-rng = np.random.default_rng()
-data = rng.standard_normal((100, 26))
-df = pd.DataFrame(data, columns=list(string.ascii_lowercase))
-df
-```
-
-## Matplotlib
-
-```{sidebar}
-Here's a sidebar to test that the code cells behave as we'd expect when there is content to the right. The code cell should be displayed to the left and with no overlap.
-```
-
-```{code-cell}
-import matplotlib.pyplot as plt
-
-fig, ax = plt.subplots()
-ax.scatter(df["a"], df["b"], c=df["b"], s=3)
-```
-
-and with the Matplotlib `plot` directive:
-
-```{eval-rst}
-.. plot::
-
-   import matplotlib.pyplot as plt
-   import numpy as np
-   rng = np.random.default_rng()
-   data = rng.standard_normal((3, 100))
-   fig, ax = plt.subplots()
-   ax.scatter(data[0], data[1], c=data[2], s=3)
-```
-
-## Plotly
-
-The HTML below shouldn't display, but it uses RequireJS to make sure that all
-works as expected. If the widgets don't show up, RequireJS may be broken.
-
-```{code-cell}
-import plotly.io as pio
-import plotly.express as px
-import plotly.offline as py
-
-pio.renderers.default = "notebook"
-
-df = px.data.iris()
-fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", size="sepal_length")
-fig
-```
-
-## Xarray
-
-Here we demonstrate `xarray` to ensure that it shows up properly.
-
-```{code-cell}
-import xarray as xr
-data = xr.DataArray(
-        np.random.randn(2, 3),
-        dims=("x", "y"),
-        coords={"x": [10, 20]}, attrs={"foo": "bar"}
-      )
-data
-```
-
-## ipyleaflet
-
-`ipyleaflet` is a **Jupyter**/**Leaflet** bridge enabling interactive maps in the Jupyter notebook environment. this demonstrate how you can integrate maps in your documentation.
-
-```{code-cell}
-from ipyleaflet import Map, basemaps
-
-# display a map centered on France
-m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])
-m
-```
diff --git a/docs/examples/subpages/pydata.ipynb b/docs/examples/subpages/pydata.ipynb
new file mode 100644
index 000000000..7282623aa
--- /dev/null
+++ b/docs/examples/subpages/pydata.ipynb
@@ -0,0 +1,148 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# PyData Library Styles\n",
+    "\n",
+    "This theme has built-in support and special styling for several major visualization libraries in the PyData ecosystem.\n",
+    "This ensures that the images and output generated by these libraries looks good for both light and dark modes.\n",
+    "Below are examples of each that we use as a benchmark for reference.\n",
+    "\n",
+    "## Pandas"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import string\n",
+    "\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "rng = np.random.default_rng()\n",
+    "data = rng.standard_normal((100, 26))\n",
+    "df = pd.DataFrame(data, columns=list(string.ascii_lowercase))\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Matplotlib"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "fig, ax = plt.subplots()\n",
+    "ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "rng = np.random.default_rng()\n",
+    "data = rng.standard_normal((3, 100))\n",
+    "fig, ax = plt.subplots()\n",
+    "ax.scatter(data[0], data[1], c=data[2], s=3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plotly\n",
+    "\n",
+    "The HTML below shouldn't display, but it uses RequireJS to make sure that all\n",
+    "works as expected. If the widgets don't show up, RequireJS may be broken."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import plotly.io as pio\n",
+    "import plotly.express as px\n",
+    "import plotly.offline as py\n",
+    "\n",
+    "pio.renderers.default = \"notebook\"\n",
+    "\n",
+    "df = px.data.iris()\n",
+    "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\")\n",
+    "fig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Xarray\n",
+    "\n",
+    "Here we demonstrate `xarray` to ensure that it shows up properly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "data = xr.DataArray(\n",
+    "        np.random.randn(2, 3),\n",
+    "        dims=(\"x\", \"y\"),\n",
+    "        coords={\"x\": [10, 20]}, attrs={\"foo\": \"bar\"}\n",
+    "      )\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ipyleaflet\n",
+    "\n",
+    "`ipyleaflet` is a **Jupyter**/**Leaflet** bridge enabling interactive maps in the Jupyter notebook environment. this demonstrate how you can integrate maps in your documentation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ipyleaflet import Map, basemaps\n",
+    "\n",
+    "# display a map centered on France\n",
+    "m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])\n",
+    "m"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/pyproject.toml b/pyproject.toml
index 05f162a50..a5f7074cb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -49,7 +49,6 @@ classifiers = [
 [project.optional-dependencies]
 doc = [
   "numpydoc",
-  "myst-nb",
   "linkify-it-py", # for link shortening
   "rich",
   "sphinxext-rediraffe",
@@ -69,8 +68,7 @@ doc = [
   "jupyterlite-sphinx",
   "sphinxcontrib-youtube<1.4",
   "sphinx-favicon>=1.0.1",
-  # Install nbsphinx in case we want to test it locally even though we can't load
-  # it at the same time as MyST-NB.
+  "ipykernel",
   "nbsphinx",
   "ipyleaflet",
   "colorama",

From 80b5cfe27a7b17533c419a8ad644bec8c508a220 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 08:19:45 +0000
Subject: [PATCH 02/18] add nbstripout to the pre-commits'

---
 .pre-commit-config.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 1b5e3aa41..cf0f3e0f2 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -38,3 +38,8 @@ repos:
     rev: v1.1.1
     hooks:
       - id: doc8
+
+  - repo: "https://github.com/kynan/nbstripout"
+    rev: "0.5.0"
+    hooks:
+      - id: nbstripout

From a40f71512cf0aa3f8f61d586d3ff89907ec19567 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 10:00:21 +0000
Subject: [PATCH 03/18] add pandoc to the readthedocs deps

---
 docs/conf.py    | 8 ++++++++
 pyproject.toml  | 1 +
 readthedocs.yml | 4 +++-
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 73d93cbf3..b42beef44 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -35,6 +35,7 @@
     "sphinx_copybutton",
     "autoapi.extension",
     # For extension examples and demos
+    "myst_parser",
     "ablog",
     "jupyter_sphinx",
     "sphinxcontrib.youtube",
@@ -65,6 +66,13 @@
     sitemap_locales = [None]
     sitemap_url_scheme = "{link}"
 
+# -- MyST options ------------------------------------------------------------
+
+# This allows us to use ::: to denote directives, useful for admonitions
+myst_enable_extensions = ["colon_fence", "linkify", "substitution"]
+myst_heading_anchors = 2
+myst_substitutions = {"rtd": "[Read the Docs](https://readthedocs.org/)"}
+
 # -- Internationalization ----------------------------------------------------
 
 # specifying the natural language populates some key tags
diff --git a/pyproject.toml b/pyproject.toml
index a5f7074cb..26e04a2f2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,6 +55,7 @@ doc = [
   "sphinx-sitemap",
   "sphinx-autoapi",
   # For examples section
+  "myst-parser",
   "ablog>=0.11.0rc2",
   "jupyter_sphinx",
   "pandas",
diff --git a/readthedocs.yml b/readthedocs.yml
index f70c87ecb..42c1763d5 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -6,7 +6,9 @@ formats:
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.9"
+    python: "3.10"
+  apt_packages:
+    - pandoc
   jobs:
     # build the gallery of themes before building the doc
     post_install:

From a4964f220f0e2cbfcff61c1f4b08418dc07cc219 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 10:02:31 +0000
Subject: [PATCH 04/18] refactor: clean the notebook

---
 docs/_contents/pydata.ipynb         | 3 +--
 docs/examples/subpages/pydata.ipynb | 3 +--
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/_contents/pydata.ipynb b/docs/_contents/pydata.ipynb
index 7282623aa..a4f5efdfd 100644
--- a/docs/_contents/pydata.ipynb
+++ b/docs/_contents/pydata.ipynb
@@ -140,8 +140,7 @@
  "metadata": {
   "language_info": {
    "name": "python"
-  },
-  "orig_nbformat": 4
+  }
  },
  "nbformat": 4,
  "nbformat_minor": 2
diff --git a/docs/examples/subpages/pydata.ipynb b/docs/examples/subpages/pydata.ipynb
index 7282623aa..a4f5efdfd 100644
--- a/docs/examples/subpages/pydata.ipynb
+++ b/docs/examples/subpages/pydata.ipynb
@@ -140,8 +140,7 @@
  "metadata": {
   "language_info": {
    "name": "python"
-  },
-  "orig_nbformat": 4
+  }
  },
  "nbformat": 4,
  "nbformat_minor": 2

From 36096f63d621d5458a4960665ceb4eead55a052e Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 10:24:38 +0000
Subject: [PATCH 05/18] move the example to the correct folder

---
 docs/{_contents => examples}/pydata.ipynb |   8 +-
 docs/examples/subpages/pydata.ipynb       | 147 ----------------------
 2 files changed, 7 insertions(+), 148 deletions(-)
 rename docs/{_contents => examples}/pydata.ipynb (96%)
 delete mode 100644 docs/examples/subpages/pydata.ipynb

diff --git a/docs/_contents/pydata.ipynb b/docs/examples/pydata.ipynb
similarity index 96%
rename from docs/_contents/pydata.ipynb
rename to docs/examples/pydata.ipynb
index a4f5efdfd..e72fcb0af 100644
--- a/docs/_contents/pydata.ipynb
+++ b/docs/examples/pydata.ipynb
@@ -138,8 +138,14 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "name": "python",
+   "version": "3.10.8"
   }
  },
  "nbformat": 4,
diff --git a/docs/examples/subpages/pydata.ipynb b/docs/examples/subpages/pydata.ipynb
deleted file mode 100644
index a4f5efdfd..000000000
--- a/docs/examples/subpages/pydata.ipynb
+++ /dev/null
@@ -1,147 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# PyData Library Styles\n",
-    "\n",
-    "This theme has built-in support and special styling for several major visualization libraries in the PyData ecosystem.\n",
-    "This ensures that the images and output generated by these libraries looks good for both light and dark modes.\n",
-    "Below are examples of each that we use as a benchmark for reference.\n",
-    "\n",
-    "## Pandas"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import string\n",
-    "\n",
-    "import numpy as np\n",
-    "import pandas as pd\n",
-    "\n",
-    "rng = np.random.default_rng()\n",
-    "data = rng.standard_normal((100, 26))\n",
-    "df = pd.DataFrame(data, columns=list(string.ascii_lowercase))\n",
-    "df"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Matplotlib"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import matplotlib.pyplot as plt\n",
-    "\n",
-    "fig, ax = plt.subplots()\n",
-    "ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import matplotlib.pyplot as plt\n",
-    "import numpy as np\n",
-    "rng = np.random.default_rng()\n",
-    "data = rng.standard_normal((3, 100))\n",
-    "fig, ax = plt.subplots()\n",
-    "ax.scatter(data[0], data[1], c=data[2], s=3)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Plotly\n",
-    "\n",
-    "The HTML below shouldn't display, but it uses RequireJS to make sure that all\n",
-    "works as expected. If the widgets don't show up, RequireJS may be broken."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import plotly.io as pio\n",
-    "import plotly.express as px\n",
-    "import plotly.offline as py\n",
-    "\n",
-    "pio.renderers.default = \"notebook\"\n",
-    "\n",
-    "df = px.data.iris()\n",
-    "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\")\n",
-    "fig"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Xarray\n",
-    "\n",
-    "Here we demonstrate `xarray` to ensure that it shows up properly."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import xarray as xr\n",
-    "data = xr.DataArray(\n",
-    "        np.random.randn(2, 3),\n",
-    "        dims=(\"x\", \"y\"),\n",
-    "        coords={\"x\": [10, 20]}, attrs={\"foo\": \"bar\"}\n",
-    "      )\n",
-    "data"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## ipyleaflet\n",
-    "\n",
-    "`ipyleaflet` is a **Jupyter**/**Leaflet** bridge enabling interactive maps in the Jupyter notebook environment. this demonstrate how you can integrate maps in your documentation."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from ipyleaflet import Map, basemaps\n",
-    "\n",
-    "# display a map centered on France\n",
-    "m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])\n",
-    "m"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 2
-}

From 8979c42505da9420e11343ea3cae9426896f619c Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 10:27:49 +0000
Subject: [PATCH 06/18] fix: solve link issue

---
 docs/user_guide/theme-elements.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md
index 919be251d..06e905224 100644
--- a/docs/user_guide/theme-elements.md
+++ b/docs/user_guide/theme-elements.md
@@ -161,7 +161,7 @@ In Python you can {python}`import sphinx`.
 ## Code execution
 
 This theme has support for Jupyter execution libraries so that you can programmatically update your documentation with each build.
-For examples, see [](../examples/pydata.md).
+For examples, see [](../examples/pydata.ipynb).
 
 ## Admonition sidebars
 

From 4b8f4380de41c31ec26407f6688c1ccb91d4db88 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 12:31:39 +0000
Subject: [PATCH 07/18] install pandoc in the test environment

---
 .github/workflows/tests.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index b1d514cc8..74f276b08 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -137,6 +137,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
+      - uses: nikeee/setup-pandoc@v1
       - name: Setup Python
         uses: actions/setup-python@v4
         with:

From e54dbb85879bc1253d5a95b710941f257ae10096 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 12:45:50 +0000
Subject: [PATCH 08/18] fix: display of large table in executed cells

---
 src/pydata_sphinx_theme/assets/styles/content/_tables.scss | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_tables.scss b/src/pydata_sphinx_theme/assets/styles/content/_tables.scss
index 480b653e3..15f37a3b6 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_tables.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_tables.scss
@@ -5,8 +5,6 @@
 // ensure table will fit in the article width and make them y-scrollable
 table {
   display: table;
-  width: fit-content;
-  max-width: 100%;
   overflow: auto;
 
   // default to table-center

From 4beba60568b2116f7fe4d412cfc59583788dac3d Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 12:55:17 +0000
Subject: [PATCH 09/18] avoid Userwarnings from matplotlib

---
 docs/examples/pydata.ipynb | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/examples/pydata.ipynb b/docs/examples/pydata.ipynb
index e72fcb0af..99c0e8693 100644
--- a/docs/examples/pydata.ipynb
+++ b/docs/examples/pydata.ipynb
@@ -45,6 +45,8 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
+    "matplotlib.set_loglevel(\"critical\")\n",
+    "\n",
     "fig, ax = plt.subplots()\n",
     "ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
    ]
@@ -57,6 +59,9 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
+    "\n",
+    "matplotlib.set_loglevel(\"critical\")\n",
+    "\n",
     "rng = np.random.default_rng()\n",
     "data = rng.standard_normal((3, 100))\n",
     "fig, ax = plt.subplots()\n",

From 9f7fe265bc36f46ef3b44690287e3fadac3633d9 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 13:07:30 +0000
Subject: [PATCH 10/18] hide the matplotlib wrning management cell

---
 docs/examples/pydata.ipynb | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/examples/pydata.ipynb b/docs/examples/pydata.ipynb
index 99c0e8693..34a8da267 100644
--- a/docs/examples/pydata.ipynb
+++ b/docs/examples/pydata.ipynb
@@ -37,6 +37,20 @@
     "## Matplotlib"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "outputs": [],
+   "source": [
+    "import matplotlib\n",
+    "\n",
+    "# avoid warnings upon doc build\n",
+    "matplotlib.set_loglevel(\"critical\")"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -45,8 +59,6 @@
    "source": [
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "matplotlib.set_loglevel(\"critical\")\n",
-    "\n",
     "fig, ax = plt.subplots()\n",
     "ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
    ]

From 0d0f5cf9673538f86b37ce72fce0e19d9e7475f9 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Wed, 27 Sep 2023 17:20:08 +0200
Subject: [PATCH 11/18] Update readthedocs.yml

---
 readthedocs.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/readthedocs.yml b/readthedocs.yml
index 42c1763d5..72526f538 100644
--- a/readthedocs.yml
+++ b/readthedocs.yml
@@ -7,8 +7,6 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.10"
-  apt_packages:
-    - pandoc
   jobs:
     # build the gallery of themes before building the doc
     post_install:

From 85fb2ebd6762a15f5e1fce9e7b54c54b32f2bcea Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Thu, 5 Oct 2023 05:57:46 +0000
Subject: [PATCH 12/18] build: use pandoc_binary to install pandoc

---
 .github/workflows/tests.yml | 2 +-
 pyproject.toml              | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 74f276b08..2463127e6 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -137,7 +137,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      - uses: nikeee/setup-pandoc@v1
+      # - uses: nikeee/setup-pandoc@v1
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
diff --git a/pyproject.toml b/pyproject.toml
index 26e04a2f2..b6ed1e82b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,6 +70,7 @@ doc = [
   "sphinxcontrib-youtube<1.4",
   "sphinx-favicon>=1.0.1",
   "ipykernel",
+  "pypandoc_binary",
   "nbsphinx",
   "ipyleaflet",
   "colorama",

From 46b1a768d28efa322aa53aae97bd7764440b12e8 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Fri, 13 Oct 2023 23:32:30 +0000
Subject: [PATCH 13/18] docs: add reference to pandoc in the setup

---
 docs/community/setup.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/community/setup.md b/docs/community/setup.md
index 6b0747666..309e53ece 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -42,6 +42,7 @@ To simplify this process, we use a few helper tools:
 - [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) compiles web assets in an automated way.
 - [pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits.
 - [nox](https://nox.thea.codes/) for automating common development tasks.
+- [pandoc](https://pandoc.org/) the universal document converter.
 
 In particular, `nox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
 The rest of this guide focuses on using `nox` to start with a basic environment.

From e530ea6cd94fec23695eaf06bf3da6eacb566de0 Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Sat, 14 Oct 2023 10:43:58 +0200
Subject: [PATCH 14/18] update docs

---
 docs/community/topics/manual-dev.md | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/docs/community/topics/manual-dev.md b/docs/community/topics/manual-dev.md
index 35964d5cc..2b05d5888 100644
--- a/docs/community/topics/manual-dev.md
+++ b/docs/community/topics/manual-dev.md
@@ -12,22 +12,26 @@ This is optional, but it's best to start with a fresh development environment so
 
 To do so, use a tool like [conda](https://docs.conda.io/en/latest/), [mamba](https://github.com/mamba-org/mamba), or [virtualenv](https://virtualenv.pypa.io/).
 
-## Clone the repository locally
+## Install dependencies
 
-First clone this repository from the `pydata` organization, or from a fork that you have created:
+You must install `sphinx-theme-builder` and Pandoc.
+
+We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme.
+Install it like so (note the `cli` option so that we can run it from the command line):
 
 ```console
-$ git clone https://github.com/pydata/pydata-sphinx-theme
-$ cd pydata-sphinx-theme
+$ pip install "sphinx-theme-builder[cli]"
 ```
 
-## Install the `sphinx-theme-builder`
+We use `nbsphinx` to support notebook (.ipynb) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) at a system level (or within a Conda environment).
 
-We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme.
-Install it like so (note the `cli` option so that we can run it from the command line):
+## Clone the repository locally
+
+First clone this repository from the `pydata` organization, or from a fork that you have created:
 
 ```console
-$ pip install sphinx-theme-builder[cli]
+$ git clone https://github.com/pydata/pydata-sphinx-theme
+$ cd pydata-sphinx-theme
 ```
 
 ## Install this theme locally
@@ -35,7 +39,7 @@ $ pip install sphinx-theme-builder[cli]
 Next, install this theme locally so that we have the necessary dependencies to build the documentation and testing suite:
 
 ```console
-$ pip install -e .[dev]
+$ pip install -e ".[dev]"
 ```
 
 Note that the `sphinx-theme-builder` will automatically install a local copy of `nodejs` for building the theme's assets.

From 5a07e18032753d5795b19e8a82c7afb271e197f7 Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Sat, 14 Oct 2023 10:44:34 +0200
Subject: [PATCH 15/18] remove pypandoc_binary

---
 pyproject.toml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index b6ed1e82b..26e04a2f2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,7 +70,6 @@ doc = [
   "sphinxcontrib-youtube<1.4",
   "sphinx-favicon>=1.0.1",
   "ipykernel",
-  "pypandoc_binary",
   "nbsphinx",
   "ipyleaflet",
   "colorama",

From e5599fde75ef1129e094a0504a93092ff45b0b19 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Sat, 14 Oct 2023 15:10:40 +0200
Subject: [PATCH 16/18] Update pyproject.toml

Co-authored-by: gabalafou <gabriel@fouasnon.com>
---
 pyproject.toml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index b6ed1e82b..26e04a2f2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -70,7 +70,6 @@ doc = [
   "sphinxcontrib-youtube<1.4",
   "sphinx-favicon>=1.0.1",
   "ipykernel",
-  "pypandoc_binary",
   "nbsphinx",
   "ipyleaflet",
   "colorama",

From 60aaae4041264e3f5f10ff547964f8ed5708b5d6 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Mon, 16 Oct 2023 23:20:34 +0200
Subject: [PATCH 17/18] ci: use back setup-pandoc

---
 .github/workflows/tests.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 2463127e6..74f276b08 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -137,7 +137,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
-      # - uses: nikeee/setup-pandoc@v1
+      - uses: nikeee/setup-pandoc@v1
       - name: Setup Python
         uses: actions/setup-python@v4
         with:

From 80141618bd3fa20bbd702f16ccce76a2dd674655 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Tue, 17 Oct 2023 08:01:36 +0000
Subject: [PATCH 18/18] Trigger CI build