fix docstrings (mostly examples)

C-Achard · Jun 11, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026
commit 9887acdbe20fd81abb2b818cb692d045a2d06bf5
diff --git a/deeplabcut/generate_training_dataset/metadata.py b/deeplabcut/generate_training_dataset/metadata.py
@@ -369,7 +369,7 @@ def update_metadata(
             if one exists
 
     Raises:
-        RuntimeError: If ``overwrite`` is False and a shuffle with the same index and
+        RuntimeError: If ``overwrite`` is ``False`` and a shuffle with the same index and
             training fraction already exists.
     """
     prefix = cfg["Task"] + cfg["date"]

diff --git a/deeplabcut/pose_estimation_pytorch/apis/evaluation.py b/deeplabcut/pose_estimation_pytorch/apis/evaluation.py
@@ -711,26 +711,26 @@ def evaluate_network(
     Examples:
         If you want to evaluate on shuffle 1 without plotting predictions.
 
-        import deeplabcut
-        deeplabcut.evaluate_network(
-            '/analysis/project/reaching-task/config.yaml', shuffles=[1],
-        )
+            import deeplabcut
+            deeplabcut.evaluate_network(
+                '/analysis/project/reaching-task/config.yaml', shuffles=[1],
+            )
 
         If you want to evaluate shuffles 0 and 1 and plot the predictions.
 
-        deeplabcut.evaluate_network(
-            '/analysis/project/reaching-task/config.yaml',
-            shuffles=[0, 1],
-            plotting=True,
-        )
+            deeplabcut.evaluate_network(
+                '/analysis/project/reaching-task/config.yaml',
+                shuffles=[0, 1],
+                plotting=True,
+            )
 
         If you want to plot assemblies for a maDLC project
 
-        deeplabcut.evaluate_network(
-            '/analysis/project/reaching-task/config.yaml',
-            shuffles=[1],
-            plotting="individual",
-        )
+            deeplabcut.evaluate_network(
+                '/analysis/project/reaching-task/config.yaml',
+                shuffles=[1],
+                plotting="individual",
+            )
     """
     cfg = auxiliaryfunctions.read_config(config)
 

diff --git a/deeplabcut/pose_estimation_pytorch/apis/export.py b/deeplabcut/pose_estimation_pytorch/apis/export.py
@@ -69,12 +69,13 @@ def export_model(
 
     Examples:
         Export the last stored snapshot for model trained with shuffle 3:
-        import deeplabcut
-        deeplabcut.export_model(
-            "/analysis/project/reaching-task/config.yaml",
-            shuffle=3,
-            snapshotindex=-1,
-        )
+
+            import deeplabcut
+            deeplabcut.export_model(
+                "/analysis/project/reaching-task/config.yaml",
+                shuffle=3,
+                snapshotindex=-1,
+            )
     """
     cfg = af.read_config(str(config))
     if iteration is not None:

diff --git a/deeplabcut/pose_estimation_pytorch/apis/videos.py b/deeplabcut/pose_estimation_pytorch/apis/videos.py
@@ -163,40 +163,40 @@ def video_inference(
     Examples:
         Bottom-up video analysis:
 
-        import deeplabcut.pose_estimation_pytorch as pep
-        from deeplabcut.core.config import read_config_as_dict
-        model_cfg = read_config_as_dict("pytorch_config.yaml")
-        runner = pep.get_pose_inference_runner(model_cfg, "snapshot.pt")
-        video_predictions = pep.video_inference("video.mp4", runner)
+            import deeplabcut.pose_estimation_pytorch as pep
+            from deeplabcut.core.config import read_config_as_dict
+            model_cfg = read_config_as_dict("pytorch_config.yaml")
+            runner = pep.get_pose_inference_runner(model_cfg, "snapshot.pt")
+            video_predictions = pep.video_inference("video.mp4", runner)
 
         Top-down video analysis:
 
-        import deeplabcut.pose_estimation_pytorch as pep
-        from deeplabcut.core.config import read_config_as_dict
-        model_cfg = read_config_as_dict("pytorch_config.yaml")
-        runner = pep.get_pose_inference_runner(model_cfg, "snapshot.pt")
-        d_runner = pep.get_pose_inference_runner(model_cfg, "snapshot-detector.pt")
-        video_predictions = pep.video_inference("video.mp4", runner, d_runner)
+            import deeplabcut.pose_estimation_pytorch as pep
+            from deeplabcut.core.config import read_config_as_dict
+            model_cfg = read_config_as_dict("pytorch_config.yaml")
+            runner = pep.get_pose_inference_runner(model_cfg, "snapshot.pt")
+            d_runner = pep.get_pose_inference_runner(model_cfg, "snapshot-detector.pt")
+            video_predictions = pep.video_inference("video.mp4", runner, d_runner)
 
 
         Top-Down pose estimation with pre-computed bounding boxes:
 
-        import numpy as np
-        import deeplabcut.pose_estimation_pytorch as pep
-        from deeplabcut.core.config import read_config_as_dict
-        video_iterator = pep.VideoIterator("video.mp4")
-        video_iterator.set_context([
-            { # frame 1 context
-                "bboxes": np.array([[12, 17, 4, 5]]),  # format (x0, y0, w, h)
-            },
-            { # frame 1 context
-                "bboxes": np.array([[12, 17, 4, 5], [18, 92, 54, 32]]),
-            },
-            ...
-        ])
-        model_cfg = read_config_as_dict("pytorch_config.yaml")
-        runner = pep.get_pose_inference_runner(model_cfg, "snapshot.pt")
-        video_predictions = pep.video_inference(video_iterator, runner)
+            import numpy as np
+            import deeplabcut.pose_estimation_pytorch as pep
+            from deeplabcut.core.config import read_config_as_dict
+            video_iterator = pep.VideoIterator("video.mp4")
+            video_iterator.set_context([
+                { # frame 1 context
+                    "bboxes": np.array([[12, 17, 4, 5]]),  # format (x0, y0, w, h)
+                },
+                { # frame 1 context
+                    "bboxes": np.array([[12, 17, 4, 5], [18, 92, 54, 32]]),
+                },
+                ...
+            ])
+            model_cfg = read_config_as_dict("pytorch_config.yaml")
+            runner = pep.get_pose_inference_runner(model_cfg, "snapshot.pt")
+            video_predictions = pep.video_inference(video_iterator, runner)
     """
     if not isinstance(video, VideoIterator):
         video = VideoIterator(str(video), cropping=cropping)

diff --git a/deeplabcut/pose_estimation_pytorch/config/make_pose_config.py b/deeplabcut/pose_estimation_pytorch/config/make_pose_config.py
@@ -305,41 +305,41 @@ def make_basic_project_config(
         `make_pytorch_pose_config`.
 
     Examples:
-        Creating a `pytorch_config` for a ResNet50 backbone with a part-affinity head (
-        as multi_animal=True and top_down=False)
-
-        import deeplabcut.pose_estimation_pytorch as pep
-        project_config = pep.config.make_basic_project_config(
-            dataset_path="/path/coco",
-            bodyparts=["nose", "left_eye", "right_eye"],
-            max_individuals=12,
-            multi_animal=True,
-        )
-        model_config = pep.config.make_pytorch_pose_config(
-            project_config=project_config,
-            pose_config_path="/path/coco/models/resnet50/pytorch_config.yaml",
-            net_type="resnet_50",
-            top_down=False,
-            save=True,
-        )
+        Creating a ``pytorch_config`` for a ResNet50 backbone with a part-affinity head (
+        ``multi_animal=True`` and ``top_down=False``)
+
+            import deeplabcut.pose_estimation_pytorch as pep
+            project_config = pep.config.make_basic_project_config(
+                dataset_path="/path/coco",
+                bodyparts=["nose", "left_eye", "right_eye"],
+                max_individuals=12,
+                multi_animal=True,
+            )
+            model_config = pep.config.make_pytorch_pose_config(
+                project_config=project_config,
+                pose_config_path="/path/coco/models/resnet50/pytorch_config.yaml",
+                net_type="resnet_50",
+                top_down=False,
+                save=True,
+            )
 
-        Creating a `pytorch_config` for a ResNet50 backbone with a simple heatmap head
-        (as the project is single-animal):
+        Creating a ``pytorch_config`` for a ResNet50 backbone with a simple heatmap head
+        (the project is single-animal):
 
-        import deeplabcut.pose_estimation_pytorch as pep
-        project_config = pep.config.make_basic_project_config(
-            dataset_path="/path/coco",
-            bodyparts=["nose", "left_eye", "right_eye"],
-            max_individuals=1,
-            multi_animal=False,
-        )
-        model_config = pep.config.make_pytorch_pose_config(
-            project_config=project_config,
-            pose_config_path="/path/coco/models/resnet50/pytorch_config.yaml",
-            net_type="resnet_50",
-            top_down=False,
-            save=True,
-        )
+            import deeplabcut.pose_estimation_pytorch as pep
+            project_config = pep.config.make_basic_project_config(
+                dataset_path="/path/coco",
+                bodyparts=["nose", "left_eye", "right_eye"],
+                max_individuals=1,
+                multi_animal=False,
+            )
+            model_config = pep.config.make_pytorch_pose_config(
+                project_config=project_config,
+                pose_config_path="/path/coco/models/resnet50/pytorch_config.yaml",
+                net_type="resnet_50",
+                top_down=False,
+                save=True,
+            )
     """
     return dict(
         project_path=str(dataset_path),

diff --git a/deeplabcut/pose_estimation_pytorch/models/backbones/resnet.py b/deeplabcut/pose_estimation_pytorch/models/backbones/resnet.py
@@ -67,12 +67,14 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
         Returns:
             torch.Tensor: Output tensor.
 
-        Example:
-            import torch
-            from deeplabcut.pose_estimation_pytorch.models.backbones import ResNet
-            backbone = ResNet(model_name="resnet50", pretrained=False)
-            x = torch.randn(1, 3, 256, 256)
-            y = backbone(x)
+        Examples:
+            Create a ResNet50 backbone and forward a random tensor:
+
+                import torch
+                from deeplabcut.pose_estimation_pytorch.models.backbones import ResNet
+                backbone = ResNet(model_name="resnet50", pretrained=False)
+                x = torch.randn(1, 3, 256, 256)
+                y = backbone(x)
 
             Expected Output Shape:
                 If input size is (batch_size, 3, shape_x, shape_y), the output shape

diff --git a/deeplabcut/pose_estimation_pytorch/models/heads/dekr.py b/deeplabcut/pose_estimation_pytorch/models/heads/dekr.py
@@ -90,11 +90,15 @@ def __init__(
             None
 
         Examples:
-            channels = (64,128,17)
-            num_blocks = 3
-            dilation_rate = 2
-            final_conv_kernel = 3
-            block = BasicBlock
+            Initialize a DEKRHeatmap:
+
+                DEKRHeatmap(
+                    channels=(64,128,17),
+                    num_blocks=3,
+                    dilation_rate=2,
+                    final_conv_kernel=3,
+                    block=BasicBlock,
+                )
         """
         super().__init__()
         self.bn_momentum = 0.1
@@ -284,13 +288,16 @@ def _make_layer(
             A sequential layer containing stacked num_blocks.
 
         Examples:
-            input:
-                block=BasicBlock
-                in_channels=64
-                out_channels=128
-                num_blocks=3
-                stride=1
-                dilation=1
+            Create a layer:
+
+                _make_layer(
+                    block=BasicBlock,
+                    in_channels=64,
+                    out_channels=128,
+                    num_blocks=3,
+                    stride=1,
+                    dilation=1,
+                )
         """
         downsample = None
         if stride != 1 or in_channels != out_channels * block.expansion:

diff --git a/deeplabcut/pose_estimation_pytorch/models/necks/utils.py b/deeplabcut/pose_estimation_pytorch/models/necks/utils.py
@@ -30,10 +30,12 @@ def make_sine_position_embedding(
     Returns:
         Sine position embeddings with shape (batch_size, d_model, h * w).
 
-    Example:
-        h, w, d_model = 10, 20, 512
-        pos_emb = make_sine_position_embedding(h, w, d_model)
-        print(pos_emb.shape)  # Output: torch.Size([1, 512, 200])
+    Examples:
+        Generate sine position embedding:
+
+            h, w, d_model = 10, 20, 512
+            pos_emb = make_sine_position_embedding(h, w, d_model)
+            print(pos_emb.shape)  # Output: torch.Size([1, 512, 200])
     """
     area = torch.ones(1, h, w)
     y_embed = area.cumsum(1, dtype=torch.float32)