Merge remote-tracking branch 'origin/stes/upgrade-docs-rebased' into aistats2025

Author: stes

.github/workflows/build.yml

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

.github/workflows/docs.yml

@@ -61,10 +61,10 @@ jobs:
           # ref: main
           ref: stes/add-xcebra
 
-      - 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: |
@@ -74,20 +74,20 @@ jobs:
           # old pandoc version (2.9.). We will hence install the latest version manually.
           # previou: sudo apt-get install -y pandoc
           # NOTE(stes): Updated to latest version as of 17/04/2025, v3.6.4.
-          wget https://github.com/jgm/pandoc/releases/download/3.6.4/pandoc-3.6.4-1-amd64.deb
+          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 --version
+          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
 

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

@@ -9,9 +9,6 @@ RUN apt-get update && apt-get install -y \
 COPY docs/requirements.txt .
 RUN pip install -r requirements.txt
 
-COPY setup.cfg .
-COPY pyproject.toml .
-COPY cebra/ .
-
-RUN pip install cebra[docs]
-RUN pip uninstall -y cebra
+#COPY setup.cfg .
+#COPY pyproject.toml .
+#COPY cebra/ .

docs/Makefile

@@ -4,11 +4,9 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?= -W --keep-going -n
-SPHINXBUILD   ?= sphinx-autobuild
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
-PORT          ?= 8000
-HOST          ?= 127.0.0.1
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -18,7 +16,7 @@ help:
 
 # Build the API documentation using sphinx
 html:
-	PYTHONPATH=.. $(SPHINXBUILD) --port $(PORT) --host $(HOST) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	PYTHONPATH=.. $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Build multiple versions
 html_versions:

docs/requirements.txt

@@ -16,3 +16,8 @@ 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

@@ -28,12 +28,11 @@
 
 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
@@ -47,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 ---------------------------------------------------
 
@@ -120,7 +128,7 @@ def get_years(start_year=2021):
 autodoc_member_order = "bysource"
 autodoc_mock_imports = [
     "torch", "nlb_tools", "tqdm", "h5py", "pandas", "matplotlib", "plotly",
-    "cvxpy", "captum"
+    "cvxpy", "captum", "joblib", "scikit-learn", "scipy", "requests", "sklearn"
 ]
 # autodoc_typehints = "none"
 

tools/build_docs.sh

@@ -11,7 +11,7 @@ docker run -u $(id -u):$(id -g) \
   -v /tmp/.cache/fontconfig:/.cache/fontconfig \
   -e MPLCONFIGDIR=/tmp/.cache/matplotlib \
   -w /app \
-  --env HOST=0.0.0.0 \
-  --env PORT=8000 \
+  --env SPHINXBUILD="sphinx-autobuild" \
+  --env SPHINXOPTS="-W --keep-going -n --port 8000 --host 0.0.0.0" \
   -it cebra-docs \
   make docs