update

.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+// container instruction for codespace users
+{
+  "name": "Python 3",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
+  "features": {
+    "ghcr.io/devcontainers-contrib/features/nox:2": {},
+    "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
+    "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {}
+  },
+  "postCreateCommand": "pre-commit install"
+}

.github/workflows/tests.yml

@@ -137,6 +137,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
+      # waiting for https://github.com/nikeee/setup-pandoc/pull/8
+      # using 12rambau fork until then
+      - uses: 12rambau/setup-pandoc@test
       - 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/community/topics/manual-dev.md

@@ -12,30 +12,34 @@ 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
 
 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.

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"
@@ -99,19 +99,21 @@
 
 # Define the version we use for matching in the version switcher.
 version_match = os.environ.get("READTHEDOCS_VERSION")
+release = pydata_sphinx_theme.__version__
 # If READTHEDOCS_VERSION doesn't exist, we're not on RTD
 # If it is an integer, we're in a PR build and the version isn't correct.
 # If it's "latest" → change to "dev" (that's what we want the switcher to call it)
 if not version_match or version_match.isdigit() or version_match == "latest":
     # For local development, infer the version to match from the package.
-    release = pydata_sphinx_theme.__version__
     if "dev" in release or "rc" in release:
         version_match = "dev"
         # We want to keep the relative reference if we are in dev mode
         # but we want the whole url if we are effectively in a released version
         json_url = "_static/switcher.json"
     else:
-        version_match = "v" + release
+        version_match = f"v{release}"
+elif version_match == "stable":
+    version_match = f"v{release}"
 
 html_theme_options = {
     "external_links": [
@@ -159,28 +161,28 @@
     "logo": {
         "text": "PyData Theme",
         "image_dark": "_static/logo-dark.svg",
-        "alt_text": "PyData Theme",
     },
     "use_edit_page_button": True,
     "show_toc_level": 1,
     "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
-    "navbar_center": ["version-switcher", "navbar-nav"],
+    # "show_nav_level": 2,
     "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
     "show_version_warning_banner": True,
-    # "show_nav_level": 2,
+    "navbar_center": ["version-switcher", "navbar-nav"],
     # "navbar_start": ["navbar-logo"],
     # "navbar_end": ["theme-switcher", "navbar-icon-links"],
     # "navbar_persistent": ["search-button"],
-    # "primary_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
-    # "article_footer_items": ["test.html", "test.html"],
-    # "content_footer_items": ["test.html", "test.html"],
-    "footer_start": ["copyright.html"],
-    "footer_center": ["sphinx-version.html"],
-    # "secondary_sidebar_items": ["page-toc.html"],  # Remove the source buttons
+    # "primary_sidebar_end": ["custom-template", "sidebar-ethical-ads"],
+    # "article_footer_items": ["test", "test"],
+    # "content_footer_items": ["test", "test"],
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    # "secondary_sidebar_items": ["page-toc"],  # Remove the source buttons
     "switcher": {
         "json_url": json_url,
         "version_match": version_match,
     },
+    "navigation_with_keys": False,
     # "search_bar_position": "navbar",  # TODO: Deprecated - remove in future version
 }
 

docs/examples/gallery.md

@@ -43,4 +43,6 @@ Thanks for your support!
   link: https://docs.pyvista.org
 - title: Pastas
   link: https://pastas.readthedocs.io/
+- title: DecentralChain
+  link: https://docs.decentralchain.io/en/master/
 ```

docs/examples/pydata.ipynb

@@ -0,0 +1,151 @@
+{
+ "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": [
+    "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
+}