[Dev docs] Clean up workflows and mike usage#3383
Draft
C-Achard wants to merge 9 commits into
Draft
Conversation
Update `_toc.yml` so the Development section points to the hosted Developer Documentation URL (`https://deeplabcut.github.io/DeepLabCut/dev/latest/`) instead of the local `docs/dev` page. This keeps the TOC aligned with the latest published developer docs.
Introduces a new reusable `deploy-dev-docs-mike` workflow to centralize Mike deploy/delete logic (including optional tag checkout, aliases, and default version handling), and updates `deploy-docs` and `manage-dev-docs` to call it instead of duplicating setup steps. `build-dev-docs` now reuses the shared dev-docs setup action and accepts a configurable MkDocs config file. Workflow names were also normalized under a `Docs / ...` prefix, and manual dev-docs management gained a `make_latest` toggle to assign and set the `latest` alias in one run.
Rename several GitHub Actions workflow display names to use a consistent `Code / ...` prefix (Codespell, pre-commit, Intelligent Python Testing, and Lockfile). This improves organization and readability in the Actions UI.
Introduce a new reusable GitHub composite action at `.github/workflows/setup-dev-docs/action.yaml` to standardize dev-docs environment setup. It configures Python (default 3.10), optionally installs Ubuntu system libraries needed by mkdocs-material social plugin rendering, and installs DeepLabCut `dev-docs` Python dependencies.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR streamlines the versioned developer documentation (MkDocs + Mike) deployment flow while reducing duplication in GitHub Actions, and aligns the main docs build with the updated dev-docs approach. It also updates many Python docstrings to a consistent Google-style format and switches the main docs build from numpydoc to sphinx.ext.napoleon.
Changes:
- Introduces a MkDocs-based, Mike-versioned developer docs site under
dev-docs/, plus workflows to build/deploy/manage versions. - Refactors docs deployment so the Jupyter Book is deployed first, then dev-docs are deployed via the shared Mike workflow.
- Updates formatting/tooling config (ruff/docformatter/mdformat) and converts many docstrings to Google-style, enabling Sphinx Napoleon.
Reviewed changes
Copilot reviewed 143 out of 150 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Adds dev-docs extras and formatting tool configs to support the new docs workflows. |
| docs/dev.md | Adds a developer-docs entry/redirect page in the main documentation tree. |
| dev-docs/mkdocs.yml | Introduces MkDocs configuration for versioned developer docs (Mike + mkdocstrings). |
| dev-docs/docs/theme/.gitkeep | Placeholder to keep theme directory in version control. |
| dev-docs/docs/get-started/index.md | Adds dev-docs landing page content for PyTorch backend developer docs. |
| dev-docs/docs/get-started/quickstart.md | Adds quickstart examples for standard + low-level PyTorch APIs. |
| dev-docs/docs/examples/index.md | Adds practical code examples for PyTorch workflows. |
| dev-docs/docs/developer-guides/training.md | Adds developer guide page for training workflows. |
| dev-docs/docs/developer-guides/tracking.md | Adds a stub tracking guide page. |
| dev-docs/docs/developer-guides/models.md | Adds developer guide page describing model architecture/components. |
| dev-docs/docs/developer-guides/inference.md | Adds developer guide page for inference/video analysis. |
| dev-docs/docs/developer-guides/index.md | Adds developer-guides index/overview page. |
| dev-docs/docs/developer-guides/dataprep.md | Adds developer guide page for data prep/loading. |
| dev-docs/docs/assets/stylesheets/.gitkeep | Placeholder to keep stylesheets directory. |
| dev-docs/docs/assets/javascripts/.gitkeep | Placeholder to keep javascripts directory. |
| deeplabcut/utils/visualization.py | Docstring reformatting/standardization. |
| deeplabcut/utils/pseudo_label.py | Docstring whitespace cleanup. |
| deeplabcut/utils/frameselectiontools.py | Docstring whitespace cleanup. |
| deeplabcut/utils/conversioncode.py | Converts docstrings to Google-style Args/Returns/Examples. |
| deeplabcut/utils/auxiliaryfunctions.py | Docstring reformatting/standardization. |
| deeplabcut/utils/auxiliaryfunctions_3d.py | Docstring whitespace cleanup. |
| deeplabcut/utils/auxfun_multianimal.py | Docstring conversions to Google style and clarifications. |
| deeplabcut/utils/auxfun_models.py | Fixes docstring quoting to a proper triple-quoted docstring. |
| deeplabcut/refine_training_dataset/tracklets.py | Improves TrackletManager docstring with clearer examples. |
| deeplabcut/pose_tracking_pytorch/tracking_utils/preprocessing.py | Docstring formatting cleanup. |
| deeplabcut/pose_tracking_pytorch/model/backbones/vit_pytorch.py | Docstring formatting improvements and example cleanup. |
| deeplabcut/pose_tracking_pytorch/apis.py | Converts API docstring to structured Args/Examples. |
| deeplabcut/pose_estimation_tensorflow/visualizemaps.py | Converts docstrings to structured Args/Returns/Examples. |
| deeplabcut/pose_estimation_tensorflow/training.py | Converts docstrings to structured Args/Returns/Examples. |
| deeplabcut/pose_estimation_tensorflow/predict_multianimal.py | Docstring whitespace cleanup. |
| deeplabcut/pose_estimation_tensorflow/nnets/conv_blocks.py | Docstring formatting and typo fix in Raises text. |
| deeplabcut/pose_estimation_tensorflow/modelzoo/api/superanimal_inference.py | Refactors docstring for clarity and structured sections. |
| deeplabcut/pose_estimation_tensorflow/modelzoo/api/spatiotemporal_adapt.py | Refactors docstring for clarity and structured sections. |
| deeplabcut/pose_estimation_tensorflow/export.py | Refactors multiple docstrings into structured format. |
| deeplabcut/pose_estimation_tensorflow/datasets/augmentation.py | Refactors transform docstring to structured format. |
| deeplabcut/pose_estimation_tensorflow/core/predict.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_tensorflow/core/predict_multianimal.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_tensorflow/config.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_tensorflow/backbones/mobilenet.py | Docstring formatting and clearer Raises docs. |
| deeplabcut/pose_estimation_tensorflow/backbones/mobilenet_v2.py | Docstring Raises wording cleanup. |
| deeplabcut/pose_estimation_tensorflow/backbones/efficientnet_model.py | Docstring spacing/structure cleanup. |
| deeplabcut/pose_estimation_tensorflow/backbones/efficientnet_builder.py | Docstring spacing/structure cleanup. |
| deeplabcut/pose_estimation_pytorch/runners/train.py | Improves docstring Raises wording. |
| deeplabcut/pose_estimation_pytorch/runners/schedulers.py | Improves docstring header and Raises wording. |
| deeplabcut/pose_estimation_pytorch/runners/inference.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_pytorch/runners/dynamic_cropping.py | Docstring examples reformatted and Raises wording improved. |
| deeplabcut/pose_estimation_pytorch/runners/ctd.py | Docstring examples reformatted. |
| deeplabcut/pose_estimation_pytorch/registry.py | Reformats examples and docstring structure across registry utilities. |
| deeplabcut/pose_estimation_pytorch/post_processing/match_predictions_to_gt.py | Docstring improvements and clearer Note section. |
| deeplabcut/pose_estimation_pytorch/post_processing/identity.py | Docstring header improvement. |
| deeplabcut/pose_estimation_pytorch/modelzoo/utils.py | Docstring Raises wording improvement. |
| deeplabcut/pose_estimation_pytorch/modelzoo/inference.py | Corrects docstring section from Raises to Warns for UserWarning. |
| deeplabcut/pose_estimation_pytorch/modelzoo/inference_helpers.py | Reformats example to a clearer multi-line snippet. |
| deeplabcut/pose_estimation_pytorch/modelzoo/fmpose_3d/fmpose3d.py | Reformats examples section into structured Examples. |
| deeplabcut/pose_estimation_pytorch/models/target_generators/pafs_targets.py | Docstring formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/target_generators/heatmap_targets.py | Docstring formatting cleanup and parameter name clarification. |
| deeplabcut/pose_estimation_pytorch/models/target_generators/dekr_targets.py | Docstring spacing cleanup. |
| deeplabcut/pose_estimation_pytorch/models/predictors/single_predictor.py | Docstring consolidation and example formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/predictors/sim_cc.py | Docstring whitespace cleanup. |
| deeplabcut/pose_estimation_pytorch/models/predictors/paf_predictor.py | Docstring structure + examples formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/predictors/dekr_predictor.py | Docstring structure + examples formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/necks/utils.py | Example formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/modules/kpt_encoders.py | Docstring whitespace cleanup. |
| deeplabcut/pose_estimation_pytorch/models/modules/gated_attention_unit.py | Docstring whitespace cleanup. |
| deeplabcut/pose_estimation_pytorch/models/modules/conv_block.py | Docstring type annotations clarified. |
| deeplabcut/pose_estimation_pytorch/models/heads/transformer.py | Docstring formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/heads/dekr.py | Docstring structure and example formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/backbones/resnet.py | Example formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/backbones/hrnet.py | Example formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/models/backbones/hrnet_coam.py | Docstring whitespace cleanup. |
| deeplabcut/pose_estimation_pytorch/data/utils.py | Docstring formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/data/transforms.py | Clarifies ValueError condition text. |
| deeplabcut/pose_estimation_pytorch/data/preprocessor.py | Docstring formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/data/postprocessor.py | Docstring formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/data/dlcloader.py | Docstring improvements and clarifications. |
| deeplabcut/pose_estimation_pytorch/data/ctd.py | Docstring formatting updates for JSON examples. |
| deeplabcut/pose_estimation_pytorch/data/cocoloader.py | Docstring Raises wording and minor formatting improvements. |
| deeplabcut/pose_estimation_pytorch/data/base.py | Docstring Raises wording and whitespace cleanup. |
| deeplabcut/pose_estimation_pytorch/config/utils.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_pytorch/config/make_pose_config.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_pytorch/apis/visualization.py | Docstring example formatting improvements. |
| deeplabcut/pose_estimation_pytorch/apis/videos.py | Docstring example formatting improvements. |
| deeplabcut/pose_estimation_pytorch/apis/utils.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_pytorch/apis/training.py | Docstring example formatting tweak. |
| deeplabcut/pose_estimation_pytorch/apis/tracklets.py | Docstring formatting cleanup. |
| deeplabcut/pose_estimation_pytorch/apis/export.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_pytorch/apis/evaluation.py | Docstring formatting improvements. |
| deeplabcut/pose_estimation_pytorch/apis/analyze_images.py | Docstring example formatting improvements. |
| deeplabcut/pose_estimation_3d/triangulation.py | Converts docstring to structured Args/Examples. |
| deeplabcut/pose_estimation_3d/plotting3D.py | Converts docstring to structured Args/Examples/Returns. |
| deeplabcut/pose_estimation_3d/camera_calibration.py | Converts docstrings to structured Args/Examples. |
| deeplabcut/modelzoo/utils.py | Docstring formatting improvements. |
| deeplabcut/modelzoo/generalized_data_converter/utils.py | Docstring whitespace cleanup. |
| deeplabcut/modelzoo/generalized_data_converter/datasets/single_dlc.py | Docstring formatting cleanup. |
| deeplabcut/modelzoo/generalized_data_converter/datasets/multi.py | Docstring whitespace cleanup. |
| deeplabcut/modelzoo/generalized_data_converter/datasets/materialize.py | Docstring whitespace cleanup. |
| deeplabcut/modelzoo/generalized_data_converter/datasets/base.py | Docstring whitespace cleanup and formatting. |
| deeplabcut/gui/tracklet_toolbox.py | Docstring conversions to proper triple-quoted docstrings and structured docs. |
| deeplabcut/gui/tabs/label_frames.py | Converts docstring to structured Args/Examples. |
| deeplabcut/gui/tabs/extract_frames.py | Converts docstring to structured Args/Returns and clarifies Raises. |
| deeplabcut/gui/tabs/create_training_dataset.py | Docstring formatting improvements and clearer Raises wording. |
| deeplabcut/generate_training_dataset/metadata.py | Updates docstring Raises sections to match RuntimeError behavior. |
| deeplabcut/create_project/new.py | Converts docstring to structured Args/Returns/Examples. |
| deeplabcut/create_project/new_3d.py | Converts docstring to structured Args/Examples. |
| deeplabcut/create_project/demo_data.py | Converts docstring to structured Args/Examples. |
| deeplabcut/create_project/add.py | Converts docstring to structured Args/Examples. |
| deeplabcut/core/trackingutils.py | Converts param docs to structured Args/Returns and improves clarity. |
| deeplabcut/core/metrics/bbox.py | Clarifies Raises docs. |
| deeplabcut/core/metrics/api.py | Reformats example output snippet for readability. |
| deeplabcut/core/debug/debug_logger.py | Converts docstrings to structured Args/Returns. |
| deeplabcut/benchmark/mot.py | Converts docstrings to structured Args/Returns and clarifies notes. |
| deeplabcut/benchmark/metrics.py | Docstring formatting cleanup. |
| deeplabcut/benchmark/base.py | Docstring whitespace cleanup. |
| conda-environments/DEEPLABCUT.yaml | Adjusts comment formatting in conda environment file. |
| .pre-commit-config.yaml | Documents mdformat hook being disabled due to upstream issue. |
| .github/workflows/setup-dev-docs/action.yaml | Adds a reusable composite action to set up dev-docs dependencies. |
| .github/workflows/publish-book.yml | Removes the old publish-book workflow (superseded by new deployment flow). |
| .github/workflows/manage-dev-docs.yml | Adds manual workflow to deploy/delete dev-docs versions and manage latest. |
| .github/workflows/lockfile-check.yml | Renames workflow display name for improved Actions UI scanning. |
| .github/workflows/intelligent-testing.yml | Splits docs builds into main-docs and dev-docs builds; renames workflow display names. |
| .github/workflows/format.yml | Renames workflow display name for improved Actions UI scanning. |
| .github/workflows/docs_and_notebooks_checks.yml | Renames workflow display name for improved Actions UI scanning. |
| .github/workflows/deploy-docs.yml | Adds consolidated docs deployment workflow (main docs + dev-docs main). |
| .github/workflows/deploy-dev-docs-mike.yml | Adds reusable Mike workflow to deploy/delete versioned dev-docs. |
| .github/workflows/codespell.yml | Renames workflow display name for improved Actions UI scanning. |
| .github/workflows/build-main-docs.yml | Renames and refines main-docs build workflow metadata. |
| .github/workflows/build-dev-docs.yml | Adds reusable build workflow for dev-docs (MkDocs). |
| _toc.yml | Updates Jupyter Book TOC to link to the versioned dev-docs site. |
| _config.yml | Switches main docs from numpydoc to Sphinx Napoleon (Google-style docstrings). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR cleans up and reduces duplication in the new versioned developer documentation setup.
Scope
The docs deployment sequence should now be clearer and less duplicated:
/dev//dev/main//dev/latest/aliasing for intended latestChanges
Docs /andCode /for easier scanning in GitHub Actions.latestand setting the/dev/default version accordingly.Notes
The main branch deployment now publishes
/dev/main/only. The/dev/latest/alias is managed through the manual dev-docs version workflow whenmake_latestis selected.