refactor: use nbsphinx as the default execution lib

.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:

.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

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.

docs/conf.py

@@ -34,18 +34,18 @@
     "sphinx_design",
     "sphinx_copybutton",
     "autoapi.extension",
-    "_extension.gallery_directive",
     # For extension examples and demos
+    "myst_parser",
     "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.
@@ -66,18 +66,18 @@
     sitemap_locales = [None]
     sitemap_url_scheme = "{link}"
 
-# -- Internationalization ----------------------------------------------------
-
-# 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/)"}
 
+# -- Internationalization ----------------------------------------------------
+
+# specifying the natural language populates some key tags
+language = "en"
+
 # -- Ablog options -----------------------------------------------------------
 
 blog_path = "examples/blog/index"

docs/examples/pydata.ipynb

@@ -0,0 +1,170 @@
+{
+ "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": {
+    "nbsphinx": "hidden"
+   },
+   "outputs": [],
+   "source": [
+    "import matplotlib\n",
+    "\n",
+    "# avoid warnings upon doc build\n",
+    "matplotlib.set_loglevel(\"critical\")"
+   ]
+  },
+  {
+   "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",
+    "\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",
+    "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": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

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
 

pyproject.toml

@@ -49,13 +49,13 @@ classifiers = [
 [project.optional-dependencies]
 doc = [
   "numpydoc",
-  "myst-nb",
   "linkify-it-py", # for link shortening
   "rich",
   "sphinxext-rediraffe",
   "sphinx-sitemap",
   "sphinx-autoapi",
   # For examples section
+  "myst-parser",
   "ablog>=0.11.0rc2",
   "jupyter_sphinx",
   "pandas",
@@ -69,8 +69,8 @@ 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",
+  "pypandoc_binary",
   "nbsphinx",
   "ipyleaflet",
   "colorama",

readthedocs.yml

@@ -6,7 +6,7 @@ formats:
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.9"
+    python: "3.10"
   jobs:
     # build the gallery of themes before building the doc
     post_install:

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