Improve documentation for local docs build (#70)

* Add dev tool for local docs build

* Update contribution guide

* Clarify local paths

* Move assets copy

* Revert docs build in makefile to old command

* Update hippocampus.py

- fix spelling errors

* Update multiobjective.py

- spelling error

---------

Co-authored-by: Mackenzie Mathis <mathis@rowland.harvard.edu>

Author: stes

.gitignore

@@ -6,6 +6,7 @@ data/
 experiments/sweeps
 exports/
 demo_notebooks/
+assets/
 
 # Binary files
 *.png

cebra/datasets/hippocampus.py

@@ -75,7 +75,7 @@
 class SingleRatDataset(cebra.data.SingleSessionDataset):
     """A single rat hippocampus tetrode recording while the rat navigates on a linear track.
 
-    Neural data is spike counts binned into 25ms time window and the continuous behavior label is position and the running driection (left, right) of a rat.
+    Neural data is spike counts binned into 25ms time window and the continuous behavior label is position and the running direction (left, right) of a rat.
     The behavior label is structured as 3D array consists of position, right, and left.
 
     Args:
@@ -152,7 +152,7 @@ def decode(self, x_train, y_train, x_test, y_test):
 class SingleRatTrialSplitDataset(SingleRatDataset):
     """A single rat hippocampus tetrode recording while the rat navigates on a linear track with 3-fold splits.
 
-    Neural data is spike counts binned into 25ms time window and the behavior is position and the running driection (left, right) of a rat.
+    Neural data is spike counts binned into 25ms time window and the behavior is position and the running direction (left, right) of a rat.
     The behavior label is structured as 3D array consists of position, right, and left.
     The neural and behavior recordings are parsed into trials (a round trip from one end of the track) and the trials are split into a train, valid and test set with k=3 nested cross validation.
 
@@ -249,7 +249,7 @@ def _split(self, split, **kwargs):
 class SingleRatCorruptDataset(SingleRatDataset):
     """A single rat hippocampus tetrode recording while the rat navigates on a linear track with a shuffled behavior label.
 
-    Neural data is spike counts binned into 25ms time window and the behavior is position and the running driection (left, right) of a rat.
+    Neural data is spike counts binned into 25ms time window and the behavior is position and the running direction (left, right) of a rat.
     The behavior label is structured as 3D array consists of position, right, and left and it is shuffled in random orders.
 
     Args:
@@ -273,7 +273,7 @@ class MultipleRatsTrialSplitDataset(cebra.data.DatasetCollection):
     """4 rats hippocampus tetrode recording while the rat navigates on a linear track with 3-fold splits.
 
     Neural and behavior recordings of 4 rats.
-    For each rat, neural data is spike counts binned into 25ms time window and the behavior is position and the running driection (left, right) of a rat.
+    For each rat, neural data is spike counts binned into 25ms time window and the behavior is position and the running direction (left, right) of a rat.
     The behavior label is structured as 3D array consists of position, right, and left.
     Neural and behavior recordings of each rat are parsed into trials (a round trip from one end of the track) and the trials are split into a train, valid and test set with k=3 nested cross validation.
 

cebra/models/multiobjective.py

@@ -67,7 +67,7 @@ class Mode:
 
         - ``OVERLAPPING``: When ``dimensions`` are set to `(x0, x1, ...)``, features will be
           extracted from ``0:x0, 0:x1, ...``.
-        - ``SEPERATE``: Features are extracted from ``x0:x1, x1:x2, ...``
+        - ``SEPARATE``: Features are extracted from ``x0:x1, x1:x2, ...``
 
         """
 

docs/source/contributing.rst

@@ -99,19 +99,45 @@ It will link the package to the local location, basically meaning any changes to
 Adding a Demo Jupyter Notebook
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-New demo notebooks should be placed in ``demo_notebooks/`` folder.
-Then the new notebook needs to be added to the Demo Notebooks ``toctree`` in ``demo_notebooks/README.rst``.
+The demo notebooks are organized in this repository: https://github.com/AdaptiveMotorControlLab/CEBRA-demos
+
+To add a demo, open a PR in that repo which adds the notebooks plus a line to the ``nbgallery`` in the README
+file: https://github.com/AdaptiveMotorControlLab/CEBRA-demos/blob/main/README.rst
+
 For that, extend the ``toctree`` (at the end of the file) using the following template:
 
-.. code:: bash
+.. code:: rst 
+
+    .. nbgallery::
+    :maxdepth: 2
+
+    Encoding of space, hippocampus (CA1) <demo_notebooks/Demo_hippocampus.ipynb>
+    Decoding movie features from (V1) visual cortex <demo_notebooks/Demo_Allen.ipynb>
+    Forelimb dynamics, somatosensory (S1) <demo_notebooks/Demo_primate_reaching.ipynb>
+    ...
 
-    <notebook_title> <demo_notebooks/<notebook_name>.ipynb>
+    Your Notebook title <demo_notebooks/<your notebook name>.ipynb>
 
-**Example:**
+Thumbnails for the notebooks can be placed in this repository
+https://github.com/AdaptiveMotorControlLab/CEBRA-assets/tree/main/docs/source/_static/thumbnails
+
+and then referenced in the documentation config:
+https://github.com/AdaptiveMotorControlLab/CEBRA/blob/bb9d55e5a533372cb011c3db322fbd9a1a5ea278/docs/source/conf.py#L203-L228
+
+To build the docs and verify the demo notebooks, you can run 
 
 .. code:: bash
 
-    Rat hippocampus <demo_notebooks/Demo_hippocampus.ipynb>
+    ./tools/build_docs.sh
+
+to build the full documentation, and render it on `http://127.0.0.1:8080` in your webbrowser to verify.
+
+For local edits,
+- CEBRA-assets is checked out under the ``/assets/`` path
+- CEBRA-figures is checkout out under the ``/docs/source/cebra-figures/`` path
+- CEBRA-demos is checkout out under the ``/docs/source/demo_notebooks/`` path
+
+You can edit files there, create branches, and re-run ``./tools/build_docs.sh`` for re-building the docs. 
 
 
 Building the Python package (information for maintainers only)

tools/build_docs.sh

@@ -0,0 +1,81 @@
+#!/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 \
+    && pip install 'cebra[docs]' && pip uninstall -y cebra
+
+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