MNT add a docs dependency group

.github/workflows/build_docs.yml

@@ -44,8 +44,7 @@ jobs:
         pip install --upgrade pip
         # force using latest nibabel
         pip install -U nibabel
-        pip install -q ipython Sphinx sphinx-gallery numpydoc # TODO: move to pyproject.toml
-        pip install -e . --group dev
+        pip install -e . --group dev --group docs
         python -c 'import cortex; print(cortex.__full_version__)'
 
     - name: Cache Playwright browsers

AGENTS.md

@@ -35,8 +35,8 @@ uv run pytest -p no:cacheprovider --no-cov -x cortex/tests/test_formats.py  # qu
 ### Docs
 
 ```bash
-uv pip install sphinx_gallery numpydoc   # not (yet) a dependency group
-cd docs && uv run make html              # gallery examples need Inkscape and Playwright too
+uv sync --all-extras --group docs        # sphinx, sphinx-gallery, numpydoc, ipython, playwright
+cd docs && uv run make html              # gallery examples also need Inkscape and Playwright Chromium
 ```
 
 ## Architecture

README.md

@@ -46,8 +46,8 @@ You can find many examples of pycortex features in the [pycortex example gallery
 
 To build the documentation locally:
 ```bash
-# Install required dependencies for the documentation
-pip install sphinx_gallery numpydoc
+# Install pycortex with the documentation dependencies (needs pip >= 25.1)
+pip install -e . --group docs
 # Move into the docs folder (assuming already in pycortex directory)
 cd docs
 # Build a local version of the documentation site

pyproject.toml

@@ -33,6 +33,15 @@ types = [
     "scipy-stubs",
 ]
 
+docs = [
+    # The gallery examples render WebGL views headlessly and use IPython.
+    "pycortex[headless]",
+    "ipython",
+    "numpydoc",
+    "sphinx",
+    "sphinx-gallery",
+]
+
 [project.optional-dependencies]
 headless = [
     "playwright>=1.58.0"