DeepLabCut · C-Achard · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -82,6 +82,27 @@ repos:
         args: [--check, --diff]
         stages: [manual]
 
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-myst
+        files: ^docs/.*\.md$
+        stages: [pre-commit]
+
+  # - repo: https://github.com/hukkin/mdformat
+  # Broken currently, replaces all autorefs with broken escaped links.
+  # See https://github.com/KyleKing/mdformat-mkdocs/issues/80
+  #   rev: 1.0.0
+  #   hooks:
+  #     - id: mdformat
+  #       additional_dependencies:
+  #         - mdformat-mkdocs==5.2.0b2
+  #       files: ^dev-docs/.*\.md$
+  #       stages: [pre-commit]
+
+
   # check only, no modifications
   - repo: local
     hooks:
@@ -91,6 +112,7 @@ repos:
         language: python
         pass_filenames: true
         files: ^(docs/|examples/(JUPYTER|COLAB)/|tools/).*(\.md|\.ipynb)$
+        exclude: ^tools/docs_audits/
         args:
           - --config
           - tools/docs_and_notebooks_report_config.yml

diff --git a/_config.yml b/_config.yml
@@ -14,8 +14,10 @@ sphinx:
       - "venv/**"
       - "**/site-packages/**"
       - "**/_build/**"
+    napoleon_google_docstring: true
+    napoleon_numpy_docstring: false
   extra_extensions:
-    - numpydoc
+    - sphinx.ext.napoleon
     - sphinxcontrib.mermaid
 
 execute:

diff --git a/deeplabcut/benchmark/base.py b/deeplabcut/benchmark/base.py
@@ -75,7 +75,6 @@ def compute_pose_map(self, results_objects):
 
     def evaluate(self, name: str, on_error="raise"):
         """Evaluate this benchmark with all registered methods."""
-
         if name not in self.names():
             raise ValueError(f"{name} is not registered. Valid names are {self.names()}")
         if on_error not in ("ignore", "return", "raise"):

diff --git a/deeplabcut/benchmark/metrics.py b/deeplabcut/benchmark/metrics.py
@@ -100,8 +100,8 @@ def calc_prediction_errors(preds, gt):
 
 def _map(strings, substrings):
     """Map image paths from predicted data to GT as the first are typically absolute
-    whereas the latter are relative to the project path."""
-
+    whereas the latter are relative to the project path.
+    """
     lookup = dict()
     strings_ = strings.copy()
     substrings_ = substrings.copy()
@@ -241,7 +241,8 @@ def calc_rmse_from_obj(
 
 def load_test_images(h5file: str, metadata: str) -> list[str]:
     """Returns the names of the test images for the benchmark, in the order
-    corresponding to the test indices."""
+    corresponding to the test indices.
+    """
     df = pd.read_hdf(h5file)
     test_indices = _load_test_indices(metadata)
     df_test = df.iloc[test_indices]

diff --git a/deeplabcut/benchmark/mot.py b/deeplabcut/benchmark/mot.py
@@ -25,22 +25,17 @@ def convert_bboxes_to_xywh(bboxes: NDArray, inplace: bool = False) -> NDArray:
     """Converts bounding box coordinates from [x_min, y_min, x_max, y_max] format to [x,
     y, width, height] format.
 
-    Parameters
-    ----------
-    bbox : numpy.ndarray
-        A 2D array of shape (N, M), where N is the number of bounding boxes
-        and M >= 4. The first four columns represent the bounding box in the format
-        [x_min, y_min, x_max, y_max].
-    inplace : bool, optional
-        If True, modifies the input array in place. If False, returns a copy of
-        the array with the converted bounding box format. Defaults to False.
-
-    Returns
-    -------
-    numpy.ndarray or None
-        If `inplace` is False, returns a new array of the same shape as `bbox`
-        with the format [x, y, width, height]. If `inplace` is True, the input
-        array is modified directly, and nothing is returned.
+    Args:
+        bboxes (numpy.ndarray): A 2D array of shape (N, M), where N is the number of bounding boxes
+            and M >= 4. The first four columns represent the bounding box in the format
+            [x_min, y_min, x_max, y_max].
+        inplace (bool, optional): If True, modifies the input array in place. If False, returns a copy of
+            the array with the converted bounding box format. Defaults to False.
+
+    Returns:
+        numpy.ndarray or None: If `inplace` is False, returns a new array of the same shape as `bboxes`
+            with the format [x, y, width, height]. If `inplace` is True, the input
+            array is modified directly, and nothing is returned.
     """
     w = bboxes[:, 2] - bboxes[:, 0]
     h = bboxes[:, 3] - bboxes[:, 1]
@@ -59,31 +54,24 @@ def convert_bboxes_to_xywh(bboxes: NDArray, inplace: bool = False) -> NDArray:
 def reconstruct_bboxes_from_bodyparts(data: pd.DataFrame, margin: float, to_xywh: bool = False) -> NDArray:
     """Reconstructs bounding boxes from body part coordinates and likelihoods.
 
-    Parameters
-    ----------
-    data : pandas.DataFrame
-        A DataFrame containing body part data with a multi-level column index.
-        The expected levels include 'x', 'y', and 'likelihood', where:
-        - 'x' and 'y' contain the coordinates of the body parts.
-        - 'likelihood' contains the confidence scores for each body part.
-    margin : float
-        The margin to add/subtract from the minimum/maximum coordinates when defining the bounding box.
-    to_xywh : bool, optional
-        If True, converts the bounding box format from [x_min, y_min, x_max, y_max]
-        to [x, y, width, height]. Defaults to False.
-
-    Returns
-    -------
-    numpy.ndarray
-        An array of shape (N, 5), where N is the number of rows in `data`.
-        Each row represents a bounding box with the following values:
-        - [x_min, y_min, x_max, y_max, likelihood]
-        If `to_xywh` is True, the format will be [x, y, width, height, likelihood].
-
-    Notes
-    -----
-    - NaN values in the input data are ignored when computing the bounding box dimensions.
-    - Warnings related to NaN values are suppressed during calculations.
+    Args:
+        data (pandas.DataFrame): A DataFrame containing body part data with a multi-level column index.
+            The expected levels include 'x', 'y', and 'likelihood', where:
+            - 'x' and 'y' contain the coordinates of the body parts.
+            - 'likelihood' contains the confidence scores for each body part.
+        margin (float): The margin to add/subtract from the minimum/maximum coordinates when defining the bounding box.
+        to_xywh (bool, optional): If True, converts the bounding box format from [x_min, y_min, x_max, y_max]
+            to [x, y, width, height]. Defaults to False.
+
+    Returns:
+        numpy.ndarray: An array of shape (N, 5), where N is the number of rows in `data`.
+            Each row represents a bounding box with the following values:
+            - [x_min, y_min, x_max, y_max, likelihood]
+            If `to_xywh` is True, the format will be [x, y, width, height, likelihood].
+
+    Note:
+        - NaN values in the input data are ignored when computing the bounding box dimensions.
+        - Warnings related to NaN values are suppressed during calculations.
     """
     x = data.xs("x", axis=1, level="coords")
     y = data.xs("y", axis=1, level="coords")
@@ -103,33 +91,26 @@ def reconstruct_bboxes_from_bodyparts(data: pd.DataFrame, margin: float, to_xywh
 def reconstruct_all_bboxes(data: pd.DataFrame, margin: float, to_xywh: bool = False) -> NDArray:
     """Reconstructs bounding boxes for multiple individuals from body part data.
 
-    Parameters
-    ----------
-    data : pandas.DataFrame
-        A DataFrame containing body part data with a multi-level column index.
-        The expected levels include:
-        - 'individuals': Names of the individuals (e.g., animals).
-        - 'x', 'y', and 'likelihood': Coordinate and confidence data for body parts.
-    margin : float
-        The margin to add/subtract from the minimum/maximum coordinates when defining the bounding box.
-    to_xywh : bool
-        If True, converts the bounding box format from [x_min, y_min, x_max, y_max]
-        to [x, y, width, height].
-
-    Returns
-    -------
-    numpy.ndarray
-        A 3D array of shape (A, F, 5), where:
-        - A is the number of individuals (excluding 'single', if present).
-        - F is the number of frames (rows) in the input `data`.
-        - Each bounding box is represented as [x_min, y_min, x_max, y_max, likelihood].
-          If `to_xywh` is True, the format will be [x, y, width, height, likelihood].
-
-    Notes
-    -----
-    - Individuals are extracted from the 'individuals' level of the DataFrame columns.
-    - If an individual named 'single' exists, it is excluded from the bounding box computation.
-    - NaN values in the input data are ignored during calculations.
+    Args:
+        data (pandas.DataFrame): A DataFrame containing body part data with a multi-level column index.
+            The expected levels include:
+            - 'individuals': Names of the individuals (e.g., animals).
+            - 'x', 'y', and 'likelihood': Coordinate and confidence data for body parts.
+        margin (float): The margin to add/subtract from the minimum/maximum coordinates when defining the bounding box.
+        to_xywh (bool, optional): If True, converts the bounding box format from [x_min, y_min, x_max, y_max]
+            to [x, y, width, height]. Defaults to False.
+
+    Returns:
+        numpy.ndarray: A 3D array of shape (A, F, 5), where:
+            - A is the number of individuals (excluding 'single', if present).
+            - F is the number of frames (rows) in the input `data`.
+            - Each bounding box is represented as [x_min, y_min, x_max, y_max, likelihood].
+              If `to_xywh` is True, the format will be [x, y, width, height, likelihood].
+
+    Note:
+        - Individuals are extracted from the 'individuals' level of the DataFrame columns.
+        - If an individual named 'single' exists, it is excluded from the bounding box computation.
+        - NaN values in the input data are ignored during calculations.
     """
     animals = data.columns.get_level_values("individuals").unique().tolist()
     try: