From 800b89cc0347148a9c7f7c023fa770260b77144c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 18:28:39 +0100
Subject: [PATCH] Add live-docs to tox

---
 docs/community/setup.md |  9 ++++-----
 pyproject.toml          |  1 +
 tox.ini                 | 15 +++++++++++++++
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/docs/community/setup.md b/docs/community/setup.md
index 33d593b80..7e1af82ce 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -101,7 +101,7 @@ The caveat to using `tox` is that this will not install the required hooks to ru
 
 Now that you have `tox` installed and cloned the repository, you should be able to build the documentation locally.
 
-To build the documentation with `nox`, run the following command:
+To build the documentation with `tox`, run the following command:
 
 ```console
 $ tox run -e docs-dev
@@ -147,16 +147,14 @@ Compiled assets are **not committed to git**.
 The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to Git history.
 ```
 
-<!-- TODO update or remove -->
-
 ## Run a development server
 
 You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window.
 
-To run the development server with `nox`, run the following command:
+To run the development server with `tox`, run the following command:
 
 ```console
-$ nox -s docs-live
+$ tox -e run docs-live
 ```
 
 When working on the theme, making changes to any of these directories:
@@ -164,6 +162,7 @@ When working on the theme, making changes to any of these directories:
 - `src/js/index.js`
 - `src/scss/index.scss`
 - `docs/**/*.rst`
+- `docs/**/*.md`
 - `docs/**/*.py`
 
 will cause the development server to do the following:
diff --git a/pyproject.toml b/pyproject.toml
index 0b155ef69..6e28eb6df 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -80,6 +80,7 @@ doc = [
 test = ["pytest", "pytest-cov", "pytest-regressions", 'sphinx[test]']
 dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
 a11y = ["pytest-playwright"]
+i18n = ["Babel", "jinja2"]
 
 [project.entry-points]
 "sphinx.html_themes" = { pydata_sphinx_theme = "pydata_sphinx_theme" }
diff --git a/tox.ini b/tox.ini
index 287d4cfda..2c4855af3 100644
--- a/tox.ini
+++ b/tox.ini
@@ -103,3 +103,18 @@ package = editable
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
+
+
+[testenv:docs-live]
+description = "Build and serve the documentation with live-reload"
+extras = 
+    dev
+    i18n
+package = editable
+deps = 
+    sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b
+# suppress Py3.11's new "can't debug frozen modules" warning
+set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
+commands = 
+    pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx
+    stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db
\ No newline at end of file