Visitar URL original
Documentation: format docstrings for dev docs by C-Achard · Pull Request #3353 · DeepLabCut/DeepLabCut · GitHub
Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
867de4c
Add mdformat hook and update docs scan/exclude
C-Achard Jun 1, 2026
0937706
Use NumPy docstring style and widen line length
C-Achard Jun 1, 2026
1a8d3cf
Format all docstrings
C-Achard Jun 1, 2026
c99aa9d
Format all docs
C-Achard Jun 1, 2026
6125126
Add dev-docs to mdformat
C-Achard Jun 1, 2026
4f32679
Disable mdformat pre-commit hook (broken)
C-Achard Jun 1, 2026
84466b0
Revert "Format all docs"
C-Achard Jun 1, 2026
794619b
use google-style docstrings + remove numpydoc
deruyter92 Jun 2, 2026
640deb2
apply ruff safe fixes all docstrings
deruyter92 Jun 2, 2026
2078850
docs: convert docstrings to Google style (batch A1)
deruyter92 Jun 3, 2026
d59328d
docs: convert docstrings to Google style (batch A2)
deruyter92 Jun 3, 2026
00425f4
docs: convert docstrings to Google style (batch A3)
deruyter92 Jun 3, 2026
0998f8e
docs: convert docstrings to Google style (batch A4)
deruyter92 Jun 3, 2026
944a561
docs: convert docstrings to Google style (batch A5)
deruyter92 Jun 3, 2026
1e33ab0
docs: convert docstrings to Google style (batch B1)
deruyter92 Jun 3, 2026
aede4c4
docs: convert docstrings to Google style (batch B2)
deruyter92 Jun 3, 2026
fd68cb0
docs: convert docstrings to Google style (batch B3)
deruyter92 Jun 3, 2026
741eb42
docs: convert docstrings to Google style (batch B4)
deruyter92 Jun 3, 2026
c046c73
docs: convert docstrings to Google style (batch B5)
deruyter92 Jun 3, 2026
1a50d1c
docs: convert docstrings to Google style (batch B6)
deruyter92 Jun 3, 2026
75046ae
docs: fix existing malformed Google style docstrings (batch C)
deruyter92 Jun 3, 2026
e589365
docs: fix existing outdated Google style docstrings (batch D)
deruyter92 Jun 3, 2026
2580c8b
doc: google docstyle fixes (audit)
deruyter92 Jun 3, 2026
c6d0a46
docs: fix examples in docstrings
deruyter92 Jun 4, 2026
dd04239
Docs: fix cli Args (was Options)
deruyter92 Jun 4, 2026
47a7485
docs: fix docstring exceptions (Raises) prose -> structured
deruyter92 Jun 4, 2026
30a2e36
docs: fix missing function descriptions in docstrings
deruyter92 Jun 4, 2026
4cbef89
docs: fix DLCLoader to_coco docstring
deruyter92 Jun 4, 2026
c949ffc
docs: manually fix incorrect args in docstrings (using griffe)
deruyter92 Jun 4, 2026
0c74661
apply suggestion: adjust comment in modelzoo.py
deruyter92 Jun 5, 2026
4fe31c5
Normalize parameter names in docstrings
C-Achard Jun 9, 2026
3b7e671
Convert doctest examples to plain code
C-Achard Jun 10, 2026
de886e7
Rename videotype to video_extensions and fix docs
C-Achard Jun 10, 2026
583170a
Update analyze_skeleton.py
C-Achard Jun 10, 2026
4eba8c3
Merge remote-tracking branch 'origin/arash/dev_docs' into cy/dev-docs…
C-Achard Jun 10, 2026
7ea3890
Fix pre-commit failures
C-Achard Jun 10, 2026
10f9644
Update uv.lock
C-Achard Jun 10, 2026
2e69e69
auto-detect URLs
deruyter92 Jun 11, 2026
a3871b6
Fix docstrings (examples) in core and create_project
deruyter92 Jun 11, 2026
9887acd
fix docstrings (mostly examples)
deruyter92 Jun 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: convert docstrings to Google style (batch A5)
  • Loading branch information
deruyter92 committed Jun 3, 2026
commit 944a56143c173775f590c4405c516cee3f0c7d86
202 changes: 78 additions & 124 deletions deeplabcut/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,37 +50,31 @@ def main(ctx, verbose):
@click.pass_context
def create_new_project(_, *args, **kwargs):
"""Create a new project directory, sub-directories and a basic configuration file.

The configuration file is loaded with default values. Change its parameters to your
projects need.\n.

Options \n
---------- \n
project : string \n
\tString containing the name of the project.\n
experimenter : string \n
\tString containing the name of the experimenter. \n
videos : list \n
\tA list of string containing the full paths of the videos to include in the project.\n
working_directory : string, optional \n
\tThe directory where the project will be created.
The default is the ``current working directory``; if provided, it must be a string\n
copy_videos : bool, optional \n
If this is set to True, the symlink of the videos are copied to the project/videos directory.
The default is ``True``; if provided it must be either ``True`` or ``False`` \n

Example \n
-------- \n
To create the project in the current working directory \n
python3 dlc.py create_new_project reaching-task
Tanmay /data/videos/mouse1.avi /data/videos/mouse2.avi /data/videos/mouse3.avi /analysis/project/

To create the project in the current working directory but do not want to create the symlinks \n
python3 dlc.py create_new_project reaching-task
Tanmay /data/videos/mouse1.avi /data/videos/mouse2.avi /data/videos/mouse3.avi /analysis/project/ -c False

To create the project in another directory \n
python3 dlc.py create_new_project reaching-task
Tanmay /data/vies/mouse1.avi /data/videos/mouse2.avi /data/videos/mouse3.avi analysis/project -d home/project
Options:
project (string): String containing the name of the project.
experimenter (string): String containing the name of the experimenter.
videos (list): A list of string containing the full paths of the videos to include in the project.
working_directory (string, optional): The directory where the project will be created.
The default is the ``current working directory``; if provided, it must be a string.
copy_videos (bool, optional): If True, symlink videos into project/videos directory.
The default is ``True``; if provided it must be either ``True`` or ``False``.

Examples:
To create the project in the current working directory \n
python3 dlc.py create_new_project reaching-task
Tanmay /data/videos/mouse1.avi /data/videos/mouse2.avi /data/videos/mouse3.avi /analysis/project/

To create the project in the current working directory but do not want to create the symlinks \n
python3 dlc.py create_new_project reaching-task
Tanmay /data/videos/mouse1.avi /data/videos/mouse2.avi /data/videos/mouse3.avi /analysis/project/ -c False

To create the project in another directory \n
python3 dlc.py create_new_project reaching-task
Tanmay /data/vies/mouse1.avi /data/videos/mouse2.avi /data/videos/mouse3.avi analysis/project -d home/project
"""
from deeplabcut.create_project import new

Expand All @@ -103,20 +97,13 @@ def create_new_project(_, *args, **kwargs):
def add_new_videos(_, *args, **kwargs):
"""Add new videos to the config file at any stage of the project.\n.

Options\n
----------\n
config : string\n
String containing the full path of the config file in the project.

videos : list \n
A list of string containing the full paths of the videos to include in the project.

copy_videos : bool, optional\n
If this is set to True, the symlink of the videos are copied to the project/videos directory. The default is
``True``; if provided it must be either ``True`` or ``False``
Options:
config (string): String containing the full path of the config file in the project.
videos (list): A list of string containing the full paths of the videos to include in the project.
copy_videos (bool, optional): If True, symlinks of the videos are copied to
project/videos. Default ``True``; must be ``True`` or ``False``.

Examples\n
--------\n
Examples:
>>> python3 dlc.py add_new_videos /home/project/reaching-task-Tanmay-2018-08-23/config.yaml /data/videos/mouse5.avi
"""
from deeplabcut.create_project import add
Expand Down Expand Up @@ -153,20 +140,16 @@ def extract_frames(_, *args, **kwargs):
MODE : string \n \n
String containing the mode of extraction. It must be either ``automatic`` or ``manual``. \n

Examples \n
-------- \n
for selecting frames automatically with 'kmeans' and do not want to crop the frames \n
>>> python3 dlc.py extract_frames /analysis/project/reaching-task/config.yaml automatic --algo kmeans \n
-------- \n
for selecting frames automatically with 'uniform' and want to
crop the frames based on the ``crop`` parameters in config.yaml \n
>>> python3 dlc.py extract_frames /analysis/project/reaching-task/config.yaml automatic --crop
-------- \n
for selecting frames manually, \n
>>> deeplabcut.extract_frames /analysis/project/reaching-task/config.yaml manual \n
While selecting the frames manually, you do not need to specify the cropping parameters.
Rather, you will get a prompt in the graphic user interface to choose if you need to crop or not. \n
-------- \n
Examples:
for selecting frames automatically with 'kmeans' and do not want to crop the frames \n
>>> python3 dlc.py extract_frames /analysis/project/reaching-task/config.yaml automatic --algo kmeans \n
for selecting frames automatically with 'uniform' and want to
crop the frames based on the ``crop`` parameters in config.yaml \n
>>> python3 dlc.py extract_frames /analysis/project/reaching-task/config.yaml automatic --crop
for selecting frames manually, \n
>>> deeplabcut.extract_frames /analysis/project/reaching-task/config.yaml manual \n
While selecting the frames manually, you do not need to specify the cropping parameters.
Rather, you will get a prompt in the graphic user interface to choose if you need to crop or not. \n
"""
from deeplabcut.generate_training_dataset.frame_extraction import extract_frames as _extract_frames

Expand All @@ -181,9 +164,8 @@ def label_frames(_, config):
"""Manually label/annotate the extracted frames. Update the list of body parts you
want to localize in the config.yaml file first.\n.

Example\n
--------\n
python3 dlc.py label_frames /analysis/project/reaching-task/config.yaml
Examples:
python3 dlc.py label_frames /analysis/project/reaching-task/config.yaml
"""
from deeplabcut.gui.tabs.label_frames import label_frames as _label_frames

Expand Down Expand Up @@ -221,13 +203,12 @@ def create_training_dataset(_, *args, **kwargs):
Update parameters TrainFraction, iteration in config.yaml
Also update parameters for pose_config.yaml as wanted.\n
CONFIG: Full path of the config.yaml file in the train directory of a project.\n
Example \n
--------\n
To create a training dataset with only 1 shuffle
python3 dlc.py create_training_dataset /analysis/project/reaching-task/config.yaml
Examples:
To create a training dataset with only 1 shuffle
python3 dlc.py create_training_dataset /analysis/project/reaching-task/config.yaml

To create a training dataset with only 2 shuffles
python3 dlc.py create_training_dataset /analysis/project/reaching-task/config.yaml num_shuffles 2
To create a training dataset with only 2 shuffles
python3 dlc.py create_training_dataset /analysis/project/reaching-task/config.yaml num_shuffles 2
"""
from deeplabcut.generate_training_dataset.trainingsetmanipulation import (
create_training_dataset as _create_training_dataset,
Expand Down Expand Up @@ -277,10 +258,9 @@ def evaluate_network(_, config, **kwargs):
"""Evaluates a trained Feature detector model.\n
CONFIG: Full path of the "pose_config.yaml" file in the train directory of a project.\n

Example\n
----------
Evalaute the network
python3 dlc.py evaluate_network /home/project/reaching/config.yaml
Examples:
Evalaute the network
python3 dlc.py evaluate_network /home/project/reaching/config.yaml

"""
from deeplabcut.pose_estimation_tensorflow.core.evaluate import evaluate_network as _evaluate_network
Expand Down Expand Up @@ -321,10 +301,9 @@ def analyze_videos(_, *args, **kwargs):
CONFIG: Full path of the "config.yaml" file in the train directory of a project.\n
VIDEOS: Full path to video.\n

Example\n
----------
Examples:

python3 dlc.py analyze_videos /home/project/reaching/config.yaml /home/project/reaching/newVideo/1.avi
python3 dlc.py analyze_videos /home/project/reaching/config.yaml /home/project/reaching/newVideo/1.avi

"""
from deeplabcut.pose_estimation_tensorflow import predict_videos
Expand Down Expand Up @@ -439,20 +418,16 @@ def extract_outlier_frames(_, *args, **kwargs):
VIDEO : Full path of the video to extract the frame from. Make sure that this video is already analyzed.


Example \n
--------\n
for extracting the frames with default settings\n
>>> python3 dlc.py extract_outlier_frames /analysis/project/reaching-task/config.yaml
... /analysis/project/video/reachinvideo1.avi \n
--------\n
for extracting the frames with kmeans\n
>>> python3 dlc.py extract_outlier_frames /analysis/project/reaching-task/config.yaml
... /analysis/project/video/reachinvideo1.avi --extractionalgorithm 'kmeans' \n
--------\n
for extracting the frames with kmeans and epsilon = 5 pixels.\n
>>> python3 dlc.py extract_outlier_frames /analysis/project/reaching-task/config.yaml
... /analysis/project/video/reachinvideo1.avi --epsilon 5 --extractionalgorithm kmeans \n
--------\n
Examples:
for extracting the frames with default settings\n
>>> python3 dlc.py extract_outlier_frames /analysis/project/reaching-task/config.yaml
... /analysis/project/video/reachinvideo1.avi \n
for extracting the frames with kmeans\n
>>> python3 dlc.py extract_outlier_frames /analysis/project/reaching-task/config.yaml
... /analysis/project/video/reachinvideo1.avi --extractionalgorithm 'kmeans' \n
for extracting the frames with kmeans and epsilon = 5 pixels.\n
>>> python3 dlc.py extract_outlier_frames /analysis/project/reaching-task/config.yaml
... /analysis/project/video/reachinvideo1.avi --epsilon 5 --extractionalgorithm kmeans \n
"""
from deeplabcut.refine_training_dataset import outlier_frames

Expand All @@ -469,10 +444,8 @@ def refine_labels(_, config):
analyze a video and extracts the outlier frames using the function
``extract_outlier_frames`` before refining the labels.\n.

Examples \n
--------\n
>>> python3 dlc.py refine_labels /analysis/project/reaching-task/config.yaml \n
--------\n
Examples:
>>> python3 dlc.py refine_labels /analysis/project/reaching-task/config.yaml \n
"""
from deeplabcut.refine_training_dataset import outlier_frames

Expand Down Expand Up @@ -560,12 +533,10 @@ def create_labeled_video(_, *args, **kwargs):
def plot_trajectories(_, *args, **kwargs):
"""Plots the trajectories of various bodyparts across the video.\n.

Example\n
--------\n
for labeling the frames\n
>>> python3 dlc.py plot_trajectories /analysis/project/reaching-task/config.yaml
Examples:
for labeling the frames\n
>>> python3 dlc.py plot_trajectories /analysis/project/reaching-task/config.yaml
/analysis/project/videos/reachingvideo1.avi \n
--------\n
"""
from deeplabcut.utils import plotting

Expand Down Expand Up @@ -638,36 +609,19 @@ def export_model(_, *args, **kwargs):
configuration, snapshot files, and frozen graph of the model to a directory named
exported-models within the project directory.

Parameters
-----------

cfg_path : string\n
\tpath to the DLC Project config.yaml file

iteration : int, optional\n
\tthe model iteration you wish to export.\n
\tIf None, uses the iteration listed in the config file

shuffle : int, optional\n
\tthe shuffle of the model to export. default = 1

trainingsetindex : int, optional\n
\tthe index of the training fraction for the model you wish to export. default = 1

snapshotindex : int, optional\n
\tthe snapshot index for the weights you wish to export.\n
\tIf None, uses the snapshotindex as defined in 'config.yaml'. Default = None

TFGPUinference : bool, optional\n
\tuse the tensorflow inference model? Default = True\n
\tFor inference using DeepLabCut-live, it is recommended to set TFGPIinference=False

overwrite : bool, optional\n
\tif the model you wish to export has already been exported, whether to overwrite. default = False

make_tar : bool, optional\n
\tDo you want to compress the exported directory to a tar file? Default = True\n
\tThis is necessary to export to the model zoo, but not for live inference.
Args:
cfg_path (string): path to the DLC Project config.yaml file.
iteration (int, optional): the model iteration you wish to export.
If None, uses the iteration listed in the config file.
shuffle (int, optional): the shuffle of the model to export. Defaults to 1.
trainingsetindex (int, optional): Index of the training fraction for the model to export. Defaults to 1.
snapshotindex (int, optional): the snapshot index for the weights you wish to export.
If None, uses the snapshotindex as defined in 'config.yaml'. Defaults to None.
TFGPUinference (bool, optional): use the tensorflow inference model? Defaults to True.
For inference using DeepLabCut-live, it is recommended to set TFGPIinference=False.
overwrite (bool, optional): If the model was already exported, whether to overwrite. Defaults to False.
make_tar (bool, optional): Do you want to compress the exported directory to a tar file? Defaults to True.
This is necessary to export to the model zoo, but not for live inference.
"""
from deeplabcut import export_model

Expand Down
Loading