From 73238ba9a2ad67f71cc431e018495614abc4ef16 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 16:49:38 +0200 Subject: [PATCH 01/16] Improve build setup for docs --- .dockerignore | 2 ++ .gitignore | 9 +++++++++ build_docs.sh | 16 ++++++++++++++++ docs/Dockerfile | 17 +++++++++++++++++ docs/Makefile | 22 +++++++++++++++++++--- docs/requirements.txt | 18 ++++++++++++++++++ setup.cfg | 11 +++++------ 7 files changed, 86 insertions(+), 9 deletions(-) create mode 100755 build_docs.sh create mode 100644 docs/Dockerfile create mode 100644 docs/requirements.txt diff --git a/.dockerignore b/.dockerignore index 3937fd07..945ab50a 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,3 +5,5 @@ tests/ third_party/ tools/ PKGBUILD + +!docs/requirements.txt diff --git a/.gitignore b/.gitignore index 30b65ee3..0563e474 100644 --- a/.gitignore +++ b/.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 diff --git a/build_docs.sh b/build_docs.sh new file mode 100755 index 00000000..ecb970de --- /dev/null +++ b/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 diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 00000000..38dd2f5c --- /dev/null +++ b/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/ . diff --git a/docs/Makefile b/docs/Makefile index 2739f4af..98f4ebbe 100644 --- a/docs/Makefile +++ b/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 git@github.com:AdaptiveMotorControlLab/cebra-figures.git source/cebra-figures +source/demo_notebooks: + git clone --depth 1 git@github.com: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 git@github.com: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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..1607c528 --- /dev/null +++ b/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 diff --git a/setup.cfg b/setup.cfg index a03d3784..560e8a3e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -64,11 +64,11 @@ 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 @@ -76,11 +76,10 @@ docs = nbsphinx nbconvert ipykernel - matplotlib<=3.5.2 + matplotlib pandas seaborn scikit-learn - numpy<2.0.0 demos = ipykernel jupyter From 7fb73932013fa045c67207e1e6af28560f44df71 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 16:51:11 +0200 Subject: [PATCH 02/16] update pydata theme options --- docs/source/conf.py | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c210526f..35cc2f3a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,8 +26,6 @@ # list see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Path setup -------------------------------------------------------------- - import datetime import os import sys @@ -60,8 +58,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 = [ @@ -133,8 +130,11 @@ def get_years(start_year=2021): # directories to ignore when looking for source files. # 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" + "**/todo", + "**/src", + "cebra-figures/figures.rst", + "cebra-figures/*.rst", + "*/cebra-figures/*.rst" #, "demo_notebooks/README.rst" ] # -- Options for HTML output ------------------------------------------------- @@ -185,23 +185,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 +292,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", +] From 34836eec6a00706f641f495cd1b0623ff16ab9ee Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 16:53:06 +0200 Subject: [PATCH 03/16] Add README for docs folder --- docs/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..84e02f2e --- /dev/null +++ b/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 +./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). From cc5f3efcaa972733010f06856e56c4115c2729ff Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 17:05:24 +0200 Subject: [PATCH 04/16] Fix demo notebook build --- docs/source/conf.py | 8 +++----- docs/source/demos.rst | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) mode change 100644 => 120000 docs/source/demos.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 35cc2f3a..7990c258 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -130,11 +130,9 @@ def get_years(start_year=2021): # directories to ignore when looking for source files. # 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" + "**/todo", "**/src", "cebra-figures/figures.rst", "cebra-figures/*.rst", + "*/cebra-figures/*.rst", "*/demo_notebooks/README.rst" + "demo_notebooks/README.rst" ] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/source/demos.rst b/docs/source/demos.rst deleted file mode 100644 index f0822386..00000000 --- a/docs/source/demos.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: demo_notebooks/README.rst diff --git a/docs/source/demos.rst b/docs/source/demos.rst new file mode 120000 index 00000000..edd57b74 --- /dev/null +++ b/docs/source/demos.rst @@ -0,0 +1 @@ +demo_notebooks/README.rst \ No newline at end of file From f4a08b5e0d5a56acfb31223c363629720aba739e Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 17:14:59 +0200 Subject: [PATCH 05/16] Finish build setup --- build_docs.sh | 16 -------- docs/README.md | 2 +- docs/source/conf.py | 2 +- tools/build_docs.sh | 92 ++++++++------------------------------------- 4 files changed, 17 insertions(+), 95 deletions(-) delete mode 100755 build_docs.sh diff --git a/build_docs.sh b/build_docs.sh deleted file mode 100755 index ecb970de..00000000 --- a/build_docs.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/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 diff --git a/docs/README.md b/docs/README.md index 84e02f2e..495e156c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +5,7 @@ This directory contains the documentation for CEBRA. To build the docs, head to *the root folder of the repository* and run: ```bash -./build_docs.sh +./tools/build_docs.sh ``` This will build the docker container in [Dockerfile](Dockerfile) and run the `make docs` command from the root repo. diff --git a/docs/source/conf.py b/docs/source/conf.py index 7990c258..11f2f042 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -131,7 +131,7 @@ 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" ] diff --git a/tools/build_docs.sh b/tools/build_docs.sh index b6a31290..01bfc79e 100755 --- a/tools/build_docs.sh +++ b/tools/build_docs.sh @@ -1,79 +1,17 @@ #!/bin/bash -# Locally build the documentation and display it in a webserver. -set -xe - -git_checkout_or_pull() { - local repo=$1 - local target_dir=$2 - # TODO(stes): theoretically we could also auto-update the repo, - # I commented this out for now to avoid interference with local - # dev/changes - #if [ -d "$target_dir" ]; then - # cd "$target_dir" - # git pull --ff-only origin main - # cd - - #else - if [ ! -d "$target_dir" ]; then - git clone "$repo" "$target_dir" - fi -} - -checkout_cebra_figures() { - git_checkout_or_pull git@github.com:AdaptiveMotorControlLab/cebra-figures.git docs/source/cebra-figures -} - -checkout_assets() { - git_checkout_or_pull git@github.com:AdaptiveMotorControlLab/cebra-assets.git assets -} - -checkout_cebra_demos() { - git_checkout_or_pull git@github.com:AdaptiveMotorControlLab/cebra-demos.git docs/source/demo_notebooks -} - -setup_python() { - python -m pip install --upgrade pip setuptools wheel - sudo apt-get install -y pandoc - pip install torch --extra-index-url=https://download.pytorch.org/whl/cpu - pip install '.[docs]' -} - -build_docs() { - cp -r assets/* . - export SPHINXOPTS="-W --keep-going -n" - (cd docs && PYTHONPATH=.. make page) -} - -serve() { - python -m http.server 8080 --b 0.0.0.0 -d docs/build/html -} - -main() { - build_docs - serve -} - -if [[ "$1" == "--build" ]]; then - main -fi - -docker build -t cebra-docs -f - . << "EOF" -FROM python:3.9 -RUN python -m pip install --upgrade pip setuptools wheel \ - && apt-get update -y && apt-get install -y pandoc git -RUN pip install torch --extra-index-url=https://download.pytorch.org/whl/cpu -COPY dist/cebra-0.5.0-py3-none-any.whl . -RUN pip install 'cebra-0.5.0-py3-none-any.whl[docs]' -EOF - -checkout_cebra_figures -checkout_assets -checkout_cebra_demos - -docker run \ - -p 127.0.0.1:8080:8080 \ - -u $(id -u):$(id -g) \ - -v .:/app -w /app \ - --tmpfs /.config --tmpfs /.cache \ - -it cebra-docs \ - ./tools/build_docs.sh --build +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 From 92c5e9e82e3d77adde80c6d409d2429c8eb7cf4a Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 19:39:27 +0200 Subject: [PATCH 06/16] update git workflow --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 826d9e91..7708cfee 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -74,7 +74,7 @@ jobs: rm pandoc-3.1.9-1-amd64.deb pip install torch --extra-index-url https://download.pytorch.org/whl/cpu pip install '.[docs]' - + pip install -r docs/requirements.txt - name: Build docs run: | From 8e3c83e05199f0e843f9299edf40159ac80e4047 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 21:18:09 +0200 Subject: [PATCH 07/16] add timeout to workflow --- .github/workflows/build.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5fed4c79..c54b4025 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,6 +10,7 @@ on: jobs: build: + timeout-minutes: 10 strategy: fail-fast: true matrix: From e794ee15ad6842ae6590126cdad80ff4934305ed Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 21:19:14 +0200 Subject: [PATCH 08/16] add timeout also to docs build --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7708cfee..33946c0a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,6 +19,7 @@ on: jobs: build: runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Cache dependencies From 8f236d146d4c80ec2d3f2418721e45e51c0cfd75 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 21:25:22 +0200 Subject: [PATCH 09/16] switch build back to sphinx for gh actions --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 33946c0a..45dd990c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -82,6 +82,7 @@ jobs: ls docs/source/cebra-figures # later also add the -n option to check for broken links export SPHINXOPTS="-W --keep-going -n" + export SPHINXBUILD="sphinx" make docs # NOTE(stes): To avoid issues as observed in From 69e22d7715042f8efbb05b5a979e879669d09391 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 21:43:05 +0200 Subject: [PATCH 10/16] attempt to fix build workflow --- .github/workflows/docs.yml | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 45dd990c..7906c05b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,7 +19,6 @@ on: jobs: build: runs-on: ubuntu-latest - timeout-minutes: 10 steps: - name: Cache dependencies @@ -56,7 +55,11 @@ jobs: with: repository: AdaptiveMotorControlLab/cebra-demos path: docs/source/demo_notebooks - ref: main + # NOTE(stes): This is a temporary branch to add the xCEBRA demo notebooks + # to the docs. Once the notebooks are merged into main, we can remove this + # branch and change the ref to main. + # ref: main + ref: stes/add-xcebra - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v5 @@ -70,19 +73,22 @@ 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 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 + pandoc --version + - name: Build docs run: | ls docs/source/cebra-figures # later also add the -n option to check for broken links export SPHINXOPTS="-W --keep-going -n" - export SPHINXBUILD="sphinx" make docs # NOTE(stes): To avoid issues as observed in From 1b8e1d7797caf89562311c7ede9f924be968a7aa Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 21:46:01 +0200 Subject: [PATCH 11/16] update to sphinx-build --- .github/workflows/docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7906c05b..cba74230 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -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 From 8f903c8442a2d47de34174a55fc4f45d9648a2d5 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 21:52:32 +0200 Subject: [PATCH 12/16] fix build workflow --- .github/workflows/docs.yml | 4 ++-- docs/Makefile | 8 +++----- tools/build_docs.sh | 4 ++-- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cba74230..f2a2bc22 100644 --- a/.github/workflows/docs.yml +++ b/.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: | diff --git a/docs/Makefile b/docs/Makefile index 98f4ebbe..26c260d3 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,12 +3,10 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-autobuild +SPHINXOPTS ?= -W --keep-going -n +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: diff --git a/tools/build_docs.sh b/tools/build_docs.sh index 01bfc79e..119272ed 100755 --- a/tools/build_docs.sh +++ b/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 From 1f924b28145b7ef5cd1d880fa87904aa4af56805 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 22:50:33 +0200 Subject: [PATCH 13/16] fix indent error --- cebra/models/criterions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cebra/models/criterions.py b/cebra/models/criterions.py index 47c2a87f..f78e298b 100644 --- a/cebra/models/criterions.py +++ b/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) From f4cd549b31e6ff9d6f725ddc2d4c3f19e9159180 Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 22:52:56 +0200 Subject: [PATCH 14/16] fix build system --- .github/workflows/docs.yml | 2 +- docs/Dockerfile | 9 +++------ docs/requirements.txt | 5 +++++ docs/source/conf.py | 19 ++++++++++++++----- 4 files changed, 23 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f2a2bc22..04953470 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -64,7 +64,7 @@ jobs: - name: Set up Python 3.10 uses: actions/setup-python@v5 with: - python-version: 3.10 + python-version: "3.10" - name: Install package run: | diff --git a/docs/Dockerfile b/docs/Dockerfile index 38dd2f5c..d96c24d2 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -6,12 +6,9 @@ RUN apt-get update && apt-get install -y \ 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/ . +#COPY setup.cfg . +#COPY pyproject.toml . +#COPY cebra/ . diff --git a/docs/requirements.txt b/docs/requirements.txt index 1607c528..880611c8 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 11f2f042..80399e5f 100644 --- a/docs/source/conf.py +++ b/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 --------------------------------------------------- @@ -119,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" From f2dd965a518fcd2d1408e2cfd59edee71d89238f Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 22:56:15 +0200 Subject: [PATCH 15/16] revert demos to main --- .github/workflows/docs.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 04953470..f99f0c72 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -55,11 +55,7 @@ jobs: with: repository: AdaptiveMotorControlLab/cebra-demos path: docs/source/demo_notebooks - # NOTE(stes): This is a temporary branch to add the xCEBRA demo notebooks - # to the docs. Once the notebooks are merged into main, we can remove this - # branch and change the ref to main. - # ref: main - ref: stes/add-xcebra + ref: main - name: Set up Python 3.10 uses: actions/setup-python@v5 From d5511086715e6f4baff02f3c6bbf26290064ca8b Mon Sep 17 00:00:00 2001 From: Steffen Schneider Date: Thu, 17 Apr 2025 23:28:48 +0200 Subject: [PATCH 16/16] increase timeout to 30 --- .github/workflows/build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c54b4025..1249f3f4 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,7 +10,7 @@ on: jobs: build: - timeout-minutes: 10 + timeout-minutes: 30 strategy: fail-fast: true matrix: