Improve build setup for docs

Author: stes

.dockerignore

@@ -5,3 +5,5 @@ tests/
 third_party/
 tools/
 PKGBUILD
+
+!docs/requirements.txt

.gitignore

@@ -8,6 +8,15 @@ exports/
 demo_notebooks/
 assets/
 
+# demo run
+.vscode/
+auxiliary_behavior_data.h5
+cebra_model.pt
+data.npz
+grid_search_models/
+neural_data.npz
+saved_models/
+
 # Binary files
 *.png
 *.jpg

build_docs.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+docker build -t cebra-docs -f docs/Dockerfile .
+docker run -u $(id -u):$(id -g) \
+  -p 127.0.0.1:8000:8000 \
+  -v $(pwd):/app \
+  -v /tmp/.cache/pip:/.cache/pip \
+  -v /tmp/.cache/sphinx:/.cache/sphinx \
+  -v /tmp/.cache/matplotlib:/.cache/matplotlib \
+  -v /tmp/.cache/fontconfig:/.cache/fontconfig \
+  -e MPLCONFIGDIR=/tmp/.cache/matplotlib \
+  -w /app \
+  --env HOST=0.0.0.0 \
+  --env PORT=8000 \
+  -it cebra-docs \
+  make docs

docs/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.10
+
+RUN apt-get update && apt-get install -y \
+    git \
+    make \
+    pandoc \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install cebra[docs]
+RUN pip uninstall -y cebra
+
+COPY docs/requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY setup.cfg .
+COPY pyproject.toml .
+COPY cebra/ .

docs/Makefile

@@ -4,9 +4,11 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= sphinx-autobuild
 SOURCEDIR     = source
 BUILDDIR      = build
+PORT          ?= 8000
+HOST          ?= 127.0.0.1
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -16,7 +18,7 @@ help:
 
 # Build the API documentation using sphinx
 html:
-	PYTHONPATH=.. $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	PYTHONPATH=.. $(SPHINXBUILD) --port $(PORT) --host $(HOST) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Build multiple versions
 html_versions:
@@ -33,12 +35,26 @@ clean:
 source/cebra-figures:
 	git clone --depth 1 [email protected]:AdaptiveMotorControlLab/cebra-figures.git source/cebra-figures
 
+source/demo_notebooks:
+	git clone --depth 1 [email protected]:AdaptiveMotorControlLab/cebra-demos.git source/demo_notebooks
+
 # Update the figures. Note that this might prompt you for an SSH key
 figures: source/cebra-figures
 	cd source/cebra-figures &&	git pull --ff-only origin main
 
+demos: source/demo_notebooks
+	cd source/demo_notebooks &&	git pull --ff-only origin main
+
+source/assets:
+	git clone --depth 1 [email protected]:AdaptiveMotorControlLab/cebra-assets.git source/assets
+
+assets: source/assets
+	cd source/assets && git pull --ff-only origin main
+	cp -r source/assets/docs/* .
+	#rm -rf source/assets
+
 # Build the page with pre-built figures
-page: source/cebra-figures html
+page: source/cebra-figures source/demo_notebooks html
 	mkdir -p page/
 	mkdir -p page/docs
 	mkdir -p page/staging/docs

docs/requirements.txt

@@ -0,0 +1,18 @@
+sphinx==7.4.7
+nbsphinx==0.9.6
+pydata-sphinx-theme==0.16.1
+pytest-sphinx==0.6.3
+sphinx-autobuild==2024.10.3
+sphinx-autodoc-typehints==1.19.0
+sphinx-copybutton==0.5.2
+sphinx-gallery==0.19.0
+sphinx-tabs==3.4.7
+sphinx-togglebutton==0.3.2
+sphinx_design==0.6.0
+sphinx_pydata_theme==0.1.0
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0

setup.cfg

@@ -64,23 +64,22 @@ integrations =
     plotly
     seaborn
 docs =
-    sphinx==5.3
-    sphinx-gallery==0.10.1
+    sphinx
+    sphinx-gallery
     docutils
-    pydata-sphinx-theme==0.9.0
-    sphinx_autodoc_typehints==1.19
+    pydata-sphinx-theme
+    sphinx_autodoc_typehints
     sphinx_copybutton
     sphinx_tabs
     sphinx_design
     sphinx_togglebutton
     nbsphinx
     nbconvert
     ipykernel
-    matplotlib<=3.5.2
+    matplotlib
     pandas
     seaborn
     scikit-learn
-    numpy<2.0.0
 demos =
     ipykernel
     jupyter