Upgrade docs build (#241)

* Improve build setup for docs

* update pydata theme options

* Add README for docs folder

* Fix demo notebook build

* Finish build setup

* update git workflow

* add timeout to workflow

* add timeout also to docs build

* switch build back to sphinx for gh actions

* attempt to fix build workflow

* update to sphinx-build

* fix build workflow

* fix indent error

* fix build system

* revert demos to main

* increase timeout to 30

Author: stes

.dockerignore

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

.github/workflows/build.yml

@@ -10,6 +10,7 @@ on:
 
 jobs:
   build:
+    timeout-minutes: 30
     strategy:
       fail-fast: true
       matrix:

.github/workflows/docs.yml

@@ -57,10 +57,10 @@ jobs:
           path: docs/source/demo_notebooks
           ref: main
 
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python 3.10
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.10"
 
       - name: Install package
         run: |
@@ -69,17 +69,21 @@ jobs:
           # as of 29/10/23. Ubuntu 22.04 which is used for ubuntu-latest only has an
           # old pandoc version (2.9.). We will hence install the latest version manually.
           # previou: sudo apt-get install -y pandoc
-          wget https://github.com/jgm/pandoc/releases/download/3.1.9/pandoc-3.1.9-1-amd64.deb
-          sudo dpkg -i pandoc-3.1.9-1-amd64.deb
-          rm pandoc-3.1.9-1-amd64.deb
-          pip install torch --extra-index-url https://download.pytorch.org/whl/cpu
-          pip install '.[docs]'
+          # NOTE(stes): Updated to latest version as of 17/04/2025, v3.6.4.
+          wget -q https://github.com/jgm/pandoc/releases/download/3.6.4/pandoc-3.6.4-1-amd64.deb
+          sudo dpkg -i pandoc-3.6.4-1-amd64.deb
+          rm pandoc-3.6.4-1-amd64.deb
+          pip install -r docs/requirements.txt
 
+      - name: Check software versions
+        run: |
+          sphinx-build --version
+          pandoc --version
 
       - name: Build docs
         run: |
           ls docs/source/cebra-figures
-          # later also add the -n option to check for broken links
+          export SPHINXBUILD="sphinx-build"
           export SPHINXOPTS="-W --keep-going -n"
           make docs
 

.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

cebra/models/criterions.py

@@ -95,7 +95,7 @@ def infonce(
 
     Note:
         - The behavior of this function changed beginning in CEBRA 0.3.0.
-        The InfoNCE implementation is numerically stabilized.
+          The InfoNCE implementation is numerically stabilized.
     """
     with torch.no_grad():
         c, _ = neg_dist.max(dim=1, keepdim=True)

docs/Dockerfile

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

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W --keep-going -n
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
@@ -33,12 +33,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/README.md

@@ -0,0 +1,14 @@
+# CEBRA documentation
+
+This directory contains the documentation for CEBRA.
+
+To build the docs, head to *the root folder of the repository* and run:
+
+```bash
+./tools/build_docs.sh
+```
+
+This will build the docker container in [Dockerfile](Dockerfile) and run the `make docs` command from the root repo.
+The exact requirements for building the docs are now listed in [requirements.txt](requirements.txt).
+
+For easier local development, docs are not using `sphinx-autobuild` and will by default be served at [http://127.0.0.1:8000](http://127.0.0.1:8000).

docs/requirements.txt

@@ -0,0 +1,23 @@
+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
+
+literate_dataclasses
+# For IPython.sphinxext.ipython_console_highlighting extension
+ipython
+numpy

docs/source/conf.py

@@ -26,16 +26,13 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
 import datetime
 import os
+import pathlib
 import sys
 
 sys.path.insert(0, os.path.abspath("."))
 
-import cebra  # noqa: E402
-
 
 def get_years(start_year=2021):
     year = datetime.datetime.now().year
@@ -49,8 +46,17 @@ def get_years(start_year=2021):
 project = "cebra"
 copyright = f"""{get_years(2021)}"""
 author = "See AUTHORS.md"
-# The full version, including alpha/beta/rc tags
-release = cebra.__version__
+version_file = pathlib.Path(
+    __file__).parent.parent.parent / "cebra" / "__init__.py"
+assert version_file.exists(), f"Could not find version file: {version_file}"
+with version_file.open("r") as f:
+    for line in f:
+        if line.startswith("__version__"):
+            version = line.split("=")[1].strip().strip('"').strip("'")
+            print("Building docs for version:", version)
+            break
+    else:
+        raise ValueError("Could not find version in __init__.py")
 
 # -- General configuration ---------------------------------------------------
 
@@ -60,8 +66,7 @@ def get_years(start_year=2021):
 
 #https://github.com/spatialaudio/nbsphinx/issues/128#issuecomment-1158712159
 html_js_files = [
-    "require.min.js",  # Add to your _static
-    "custom.js",
+    "https://cdn.plot.ly/plotly-latest.min.js",  # Add Plotly.js
 ]
 
 extensions = [
@@ -122,7 +127,8 @@ def get_years(start_year=2021):
 
 autodoc_member_order = "bysource"
 autodoc_mock_imports = [
-    "torch", "nlb_tools", "tqdm", "h5py", "pandas", "matplotlib", "plotly"
+    "torch", "nlb_tools", "tqdm", "h5py", "pandas", "matplotlib", "plotly",
+    "joblib", "scikit-learn", "scipy", "requests", "sklearn"
 ]
 # autodoc_typehints = "none"
 
@@ -134,7 +140,8 @@ def get_years(start_year=2021):
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
     "**/todo", "**/src", "cebra-figures/figures.rst", "cebra-figures/*.rst",
-    "*/cebra-figures/*.rst", "demo_notebooks/README.rst"
+    "*/cebra-figures/*.rst", "*/demo_notebooks/README.rst",
+    "demo_notebooks/README.rst"
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -185,23 +192,26 @@ def get_years(start_year=2021):
             "icon": "fas fa-graduation-cap",
         },
     ],
-    "external_links": [
-        # {"name": "Mathis Lab", "url": "http://www.mackenziemathislab.org/"},
-    ],
     "collapse_navigation": False,
-    "navigation_depth": 4,
+    "navigation_depth": 1,
     "show_nav_level": 2,
     "navbar_align": "content",
     "show_prev_next": False,
+    "navbar_end": ["theme-switcher", "navbar-icon-links.html"],
+    "navbar_persistent": [],
+    "header_links_before_dropdown": 7
 }
 
-html_context = {"default_mode": "dark"}
+html_context = {"default_mode": "light"}
 html_favicon = "_static/img/logo_small.png"
 html_logo = "_static/img/logo_large.png"
 
-# Remove the search field for now
+# Replace with this configuration to enable "on this page" navigation
 html_sidebars = {
-    "**": ["search-field.html", "sidebar-nav-bs.html"],
+    "**": ["search-field.html", "sidebar-nav-bs", "page-toc.html"],
+    "demos": ["search-field.html", "sidebar-nav-bs"],
+    "api": ["search-field.html", "sidebar-nav-bs"],
+    "figures": ["search-field.html", "sidebar-nav-bs"],
 }
 
 # Disable links for embedded images
@@ -289,3 +299,12 @@ def get_years(start_year=2021):
 """
 # fmt: on
 # flake8: enable=E501
+
+# Configure nbsphinx to properly render Plotly plots
+nbsphinx_execute = 'auto'
+nbsphinx_allow_errors = True
+nbsphinx_requirejs_path = 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.7/require.js'
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'png', 'svg', 'pdf'}",
+    "--InlineBackend.rc=figure.dpi=96",
+]