Restructure API docs for integrations (#103)

AdaptiveMotorControlLab · Oct 29, 2023 · 4e594a4 · 4e594a4
1 parent f0fe607
commit 4e594a4
Show file tree

Hide file tree

Showing 11 changed files with 64 additions and 20 deletions.
diff --git a/.github/workflows/docs.yml b/.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]'
 

diff --git a/cebra/data/load.py b/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

diff --git a/cebra/integrations/plotly.py b/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:

diff --git a/docs/source/api.rst b/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
diff --git a/docs/source/api/integrations/data.rst b/docs/source/api/integrations/data.rst
@@ -0,0 +1,6 @@
+Data Loading
+------------
+
+.. automodule:: cebra.data.load
+   :show-inheritance:
+   :members:
diff --git a/docs/source/api/integrations/deeplabcut.rst b/docs/source/api/integrations/deeplabcut.rst
@@ -0,0 +1,8 @@
+DeepLabCut
+----------
+
+.. automodule:: cebra.integrations.deeplabcut
+   :show-inheritance:
+   :members:
+
+
diff --git a/docs/source/api/integrations/matplotlib.rst b/docs/source/api/integrations/matplotlib.rst
@@ -0,0 +1,7 @@
+Plotting with ``matplotlib``
+----------------------------
+
+.. automodule:: cebra.integrations.matplotlib
+   :show-inheritance:
+   :members:
+
diff --git a/docs/source/api/integrations/plotly.rst b/docs/source/api/integrations/plotly.rst
@@ -0,0 +1,7 @@
+Plotting with ``plotly``
+----------------------------
+
+.. automodule:: cebra.integrations.plotly
+   :show-inheritance:
+   :members:
+
diff --git a/docs/source/api/pytorch/helpers.rst b/docs/source/api/pytorch/helpers.rst
@@ -21,14 +21,6 @@ Registry
    :show-inheritance:
 
 
-Plots
------
-
-.. automodule:: cebra.integrations.matplotlib
-   :show-inheritance:
-   :members:
-
-
 Grid-Search
 -----------
 

diff --git a/docs/source/api/pytorch/integrations.rst b/docs/source/api/pytorch/integrations.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -101,6 +101,7 @@ def get_years(start_year=2021):
     "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None),
     "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
     "joblib": ("https://joblib.readthedocs.io/en/latest/", None),
+    "plotly": ("https://plotly.com/python-api-reference/", None)
 }
 
 # Config is documented here: https://sphinx-copybutton.readthedocs.io/en/latest/
@@ -116,6 +117,7 @@ def get_years(start_year=2021):
     "h5py",
     "pandas",
     "matplotlib",
+    "plotly"
 ]
 # autodoc_typehints = "none"