Restructure API docs for integrations (#103)

Author: stes

.github/workflows/docs.yml

@@ -59,7 +59,13 @@ jobs:
       - name: Install package
         run: |
           python -m pip install --upgrade pip setuptools wheel
-          sudo apt-get install -y pandoc
+          # NOTE(stes) Pandoc version must be at least (2.14.2) but less than (4.0.0).
+          # 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]'
 

cebra/data/load.py

@@ -9,7 +9,22 @@
 # Please see LICENSE.md for the full license document:
 # https://github.com/AdaptiveMotorControlLab/CEBRA/LICENSE.md
 #
-"""A simple API for loading various data formats used with CEBRA."""
+"""A simple API for loading various data formats used with CEBRA.
+
+Availability of different data formats depends on the installed
+dependencies. If a dependency is not installed, an attempt to load
+a file of that format will throw an error with further installation
+instructions.
+
+Currently available formats:
+
+- HDF5 via ``h5py``
+- Pickle files via ``pickle``
+- Joblib files via ``joblib``
+- Various dataframe formats via ``pandas``.
+- Matlab files via ``scipy.io.loadmat``
+- DeepLabCut (single animal) files via ``deeplabcut``
+"""
 
 import abc
 import pathlib

cebra/integrations/plotly.py

@@ -135,7 +135,7 @@ def plot_embedding_interactive(
     This is supposing that the dimensions provided to ``idx_order`` are in the range of the number of
     dimensions of the embedding (i.e., between 0 and :py:attr:`cebra.CEBRA.output_dimension` -1).
 
-    The function makes use of :py:func:`plotly.graph_objs._scatter.Scatter` and parameters from that function can be provided
+    The function makes use of :py:class:`plotly.graph_objects.Scatter` and parameters from that function can be provided
     as part of ``kwargs``.
 
 
@@ -156,7 +156,7 @@ def plot_embedding_interactive(
         title: The title on top of the embedding.
         figsize: Figure width and height in inches.
         dpi: Figure resolution.
-        kwargs: Optional arguments to customize the plots. See :py:func:`plotly.graph_objs._scatter.Scatter` documentation for more
+        kwargs: Optional arguments to customize the plots. See :py:class:`plotly.graph_objects.Scatter` documentation for more
             details on which arguments to use.
 
     Returns:

docs/source/api.rst

@@ -37,8 +37,16 @@ these components in other contexts and research code bases.
    api/pytorch/datasets
    api/pytorch/distributions
    api/pytorch/models
-   api/pytorch/integrations
    api/pytorch/helpers
 
+.. toctree::
+   :hidden:
+   :caption: Integrations
+
+   api/integrations/data
+   api/integrations/matplotlib
+   api/integrations/plotly
+   api/integrations/deeplabcut
+
 
 .. _Scikit-learn estimators: https://scikit-learn.org/stable/developers/develop.html

docs/source/api/integrations/data.rst

@@ -0,0 +1,6 @@
+Data Loading
+------------
+
+.. automodule:: cebra.data.load
+   :show-inheritance:
+   :members:

docs/source/api/integrations/deeplabcut.rst

@@ -0,0 +1,8 @@
+DeepLabCut
+----------
+
+.. automodule:: cebra.integrations.deeplabcut
+   :show-inheritance:
+   :members:
+
+

docs/source/api/integrations/matplotlib.rst

@@ -0,0 +1,7 @@
+Plotting with ``matplotlib``
+----------------------------
+
+.. automodule:: cebra.integrations.matplotlib
+   :show-inheritance:
+   :members:
+

docs/source/api/integrations/plotly.rst

@@ -0,0 +1,7 @@
+Plotting with ``plotly``
+----------------------------
+
+.. automodule:: cebra.integrations.plotly
+   :show-inheritance:
+   :members:
+

docs/source/api/pytorch/helpers.rst

@@ -21,14 +21,6 @@ Registry
    :show-inheritance:
 
 
-Plots
------
-
-.. automodule:: cebra.integrations.matplotlib
-   :show-inheritance:
-   :members:
-
-
 Grid-Search
 -----------