Re-organise API reference

CONTRIBUTING.md

@@ -209,24 +209,31 @@ If it is not yet defined and you have multiple external links pointing to the sa
 
 
 ### Updating the API reference
-If your PR introduces new public-facing functions, classes, or methods,
-make sure to add them to the `docs/source/api_index.rst` page, so that they are
-included in the [API reference](target-api),
-e.g.:
+If your PR introduces new public modules, or renames existing ones,
+make sure to add them to the `docs/source/api_index.rst` page, so that they are included in the [API reference](target-api), e.g.:
 
 ```rst
-My new module
---------------
-.. currentmodule:: movement.new_module
+API Reference
+=============
+
+Information on specific functions, classes, and methods.
+
+.. rubric:: Modules
+
 .. autosummary::
     :toctree: api
+    :recursive:
+    :nosignatures:
 
-    new_function
-    NewClass
+    movement.move_accessor
+    movement.io.load_poses
+    movement.io.save_poses
+    movement.your_new_module
 ```
 
-For this to work, your functions/classes/methods will need to have docstrings
-that follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) style.
+The API reference is auto-generated by the `sphinx-autodoc` and `sphinx-autosummary` plugins, based on docstrings.
+So make sure that all your public functions/classes/methods have valid docstrings following the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) style.
+Our `pre-commit` hooks include some checks (`ruff` rules) that ensure the docstrings are formatted consistently.
 
 ### Updating the examples
 We use [sphinx-gallery](sphinx-gallery:)

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,31 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   {% set ns = namespace(has_public_methods=false) %}
+
+   {% if methods %}
+   {% for item in methods %}
+   {% if not item.startswith('_') %}
+   {% set ns.has_public_methods = true %}
+   {% endif %}
+   {%- endfor %}
+   {% endif %}
+
+   {% if ns.has_public_methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+   {% if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+   {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/_templates/autosummary/function.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,31 @@
+{{ fullname | escape | underline }}
+
+.. rubric:: Description
+
+.. automodule:: {{ fullname }}
+
+.. currentmodule:: {{ fullname }}
+
+{% if classes %}
+.. rubric:: Classes
+
+.. autosummary::
+    :toctree: .
+    :nosignatures:
+    {% for class in classes %}
+    {{ class.split('.')[-1] }}
+    {% endfor %}
+
+{% endif %}
+
+{% if functions %}
+.. rubric:: Functions
+
+.. autosummary::
+    :toctree: .
+    :nosignatures:
+    {% for function in functions %}
+    {{ function.split('.')[-1] }}
+    {% endfor %}
+
+{% endif %}

docs/source/api_index.rst

@@ -3,104 +3,22 @@
 API Reference
 =============
 
+Information on specific functions, classes, and methods.
 
-Load poses
-----------
-.. currentmodule:: movement.io.load_poses
-.. autosummary::
-    :toctree: api
-
-    from_numpy
-    from_file
-    from_sleap_file
-    from_dlc_file
-    from_lp_file
-    from_dlc_style_df
-
-Save poses
-----------
-
-.. currentmodule:: movement.io.save_poses
-.. autosummary::
-    :toctree: api
-
-    to_dlc_file
-    to_lp_file
-    to_sleap_analysis_file
-    to_dlc_style_df
-
-Validators - Files
-------------------
-.. currentmodule:: movement.validators.files
-.. autosummary::
-    :toctree: api
-
-    ValidFile
-    ValidHDF5
-    ValidDeepLabCutCSV
-
-Validators - Datasets
-----------------------
-.. currentmodule:: movement.validators.datasets
-.. autosummary::
-    :toctree: api
-
-    ValidPosesDataset
-
-Sample Data
------------
-.. currentmodule:: movement.sample_data
-.. autosummary::
-    :toctree: api
-
-    list_datasets
-    fetch_dataset_paths
-    fetch_dataset
-
-Filtering
----------
-.. currentmodule:: movement.filtering
-.. autosummary::
-    :toctree: api
-
-    filter_by_confidence
-    median_filter
-    savgol_filter
-    interpolate_over_time
-    report_nan_values
-
-
-Analysis
---------
-.. currentmodule:: movement.analysis.kinematics
-.. autosummary::
-    :toctree: api
-
-    compute_displacement
-    compute_velocity
-    compute_acceleration
-
-.. currentmodule:: movement.utils.vector
-.. autosummary::
-    :toctree: api
-
-    cart2pol
-    pol2cart
-
-MovementDataset
----------------
-.. currentmodule:: movement.move_accessor
-.. autosummary::
-    :toctree: api
-
-    MovementDataset
+.. rubric:: Modules
 
-Logging
--------
-.. currentmodule:: movement.utils.logging
 .. autosummary::
     :toctree: api
+    :recursive:
+    :nosignatures:
 
-    configure_logging
-    log_error
-    log_warning
+    movement.move_accessor
+    movement.io.load_poses
+    movement.io.save_poses
+    movement.filtering
+    movement.analysis.kinematics
+    movement.utils.vector
+    movement.utils.logging
+    movement.sample_data
+    movement.validators.files
+    movement.validators.datasets

movement/analysis/kinematics.py

@@ -1,4 +1,4 @@
-"""Functions for computing kinematic variables."""
+"""Compute kinematic variables like velocity and acceleration."""
 
 import numpy as np
 import xarray as xr

movement/filtering.py

@@ -1,4 +1,4 @@
-"""Functions for filtering and interpolating pose tracks in xarray datasets."""
+"""Filter and interpolate  pose tracks in ``movement`` datasets."""
 
 import logging
 from datetime import datetime

movement/io/load_poses.py

@@ -1,4 +1,4 @@
-"""Functions for loading pose tracking data from various frameworks."""
+"""Load pose tracking data from various frameworks into ``movement``."""
 
 import logging
 from pathlib import Path

movement/io/save_poses.py

@@ -1,4 +1,4 @@
-"""Functions for saving pose tracking data to various file formats."""
+"""Save pose tracking data from ``movement`` to various file formats."""
 
 import logging
 from pathlib import Path

movement/move_accessor.py

@@ -1,4 +1,4 @@
-"""Accessor for extending xarray.Dataset objects."""
+"""Accessor for extending :py:class:`xarray.Dataset` objects."""
 
 import logging
 from typing import ClassVar
@@ -28,22 +28,26 @@ class MovementDataset:
     ``movement``-specific methods are accessed using the ``move`` keyword,
     for example ``ds.move.validate()`` (see [1]_ for more details).
 
+    Attributes
+    ----------
+    dim_names : tuple
+        Names of the expected dimensions in the dataset.
+    var_names : tuple
+        Names of the expected data variables in the dataset.
 
     References
     ----------
     .. [1] https://docs.xarray.dev/en/stable/internals/extending-xarray.html
 
     """
 
-    # Names of the expected dimensions in the dataset
     dim_names: ClassVar[tuple] = (
         "time",
         "individuals",
         "keypoints",
         "space",
     )
 
-    # Names of the expected data variables in the dataset
     var_names: ClassVar[tuple] = (
         "position",
         "confidence",

movement/sample_data.py

@@ -1,4 +1,4 @@
-"""Module for fetching and loading sample datasets.
+"""Fetch and load sample datasets.
 
 This module provides functions for fetching and loading sample data used in
 tests, examples, and tutorials. The data are stored in a remote repository

movement/validators/datasets.py

@@ -1,4 +1,4 @@
-"""`attrs` classes for validating data structures."""
+"""``attrs`` classes for validating data structures."""
 
 from collections.abc import Iterable
 from typing import Any

movement/validators/files.py

@@ -1,4 +1,4 @@
-"""`attrs` classes for validating file paths."""
+"""``attrs`` classes for validating file paths."""
 
 import os
 from pathlib import Path
@@ -14,7 +14,7 @@
 class ValidFile:
     """Class for validating file paths.
 
-    Parameters
+    Attributes
     ----------
     path : str or pathlib.Path
         Path to the file.
@@ -49,7 +49,7 @@ class ValidFile:
     expected_suffix: list[str] = field(factory=list, kw_only=True)
 
     @path.validator
-    def path_is_not_dir(self, attribute, value):
+    def _path_is_not_dir(self, attribute, value):
         """Ensure that the path does not point to a directory."""
         if value.is_dir():
             raise log_error(
@@ -58,7 +58,7 @@ def path_is_not_dir(self, attribute, value):
             )
 
     @path.validator
-    def file_exists_when_expected(self, attribute, value):
+    def _file_exists_when_expected(self, attribute, value):
         """Ensure that the file exists (or not) as needed.
 
         This depends on the expected usage (read and/or write).
@@ -75,7 +75,7 @@ def file_exists_when_expected(self, attribute, value):
                 )
 
     @path.validator
-    def file_has_access_permissions(self, attribute, value):
+    def _file_has_access_permissions(self, attribute, value):
         """Ensure that the file has the expected access permission(s).
 
         Raises a PermissionError if not.
@@ -96,7 +96,7 @@ def file_has_access_permissions(self, attribute, value):
             )
 
     @path.validator
-    def file_has_expected_suffix(self, attribute, value):
+    def _file_has_expected_suffix(self, attribute, value):
         """Ensure that the file has one of the expected suffix(es)."""
         if self.expected_suffix and value.suffix not in self.expected_suffix:
             raise log_error(
@@ -110,7 +110,7 @@ def file_has_expected_suffix(self, attribute, value):
 class ValidHDF5:
     """Class for validating HDF5 files.
 
-    Parameters
+    Attributes
     ----------
     path : pathlib.Path
         Path to the HDF5 file.
@@ -130,7 +130,7 @@ class ValidHDF5:
     expected_datasets: list[str] = field(factory=list, kw_only=True)
 
     @path.validator
-    def file_is_h5(self, attribute, value):
+    def _file_is_h5(self, attribute, value):
         """Ensure that the file is indeed in HDF5 format."""
         try:
             with h5py.File(value, "r") as f:
@@ -142,7 +142,7 @@ def file_is_h5(self, attribute, value):
             ) from e
 
     @path.validator
-    def file_contains_expected_datasets(self, attribute, value):
+    def _file_contains_expected_datasets(self, attribute, value):
         """Ensure that the HDF5 file contains the expected datasets."""
         if self.expected_datasets:
             with h5py.File(value, "r") as f:
@@ -159,7 +159,7 @@ def file_contains_expected_datasets(self, attribute, value):
 class ValidDeepLabCutCSV:
     """Class for validating DeepLabCut-style .csv files.
 
-    Parameters
+    Attributes
     ----------
     path : pathlib.Path
         Path to the .csv file.
@@ -175,7 +175,7 @@ class ValidDeepLabCutCSV:
     path: Path = field(validator=validators.instance_of(Path))
 
     @path.validator
-    def csv_file_contains_expected_levels(self, attribute, value):
+    def _csv_file_contains_expected_levels(self, attribute, value):
         """Ensure that the .csv file contains the expected index column levels.
 
         These are to be found among the top 4 rows of the file.