Docs audit [April 2026]: Add dev docs by deruyter92 · Pull Request #3336 · DeepLabCut/DeepLabCut

deruyter92 · 2026-05-19T14:43:08Z

Replacement PR for #3187 by @arashsm79 (credits go to @arashsm79, see the original PR for commit history).

Progress:

rebased on main
moved dev docs to root (include deeplabcut.core and other deeplabcut APIs)
fix CI build for mkdocs
update configuration and custom models sections
remove incomplete docs from index
add versioning deployment + workflows

Description

Dev docs: build & deploy approach

This PR adds a second documentation site alongside the existing Jupyter Book, aimed at maintainers and developers. It lives under /dev/ on GitHub Pages and is versioned with mike.

What gets built

API docs: all API in deeplabcut, except cli, gui, benchmark, version -> should probably be limited further as most API has no clear docstrings currently, and some are distracting from the main APIs.
Integration with main docs: _toc.yml links to docs/dev.md, which redirects to /dev/ (mike default → /dev/main/)

CI on PRs (build only)

build-dev-docs.yml — reusable workflow; installs .[dev-docs] + cairo deps, runs mkdocs build -f dev-docs/mkdocs.yml
Called from intelligent-testing.yml when the docs lane runs
Validates the site builds; does not deploy

Auto-deploy on push to `main`

deploy-docs.yml publishes both doc sets to the gh-pages branch:

Build Jupyter Book (build-main-docs.yml) → artifact
Deploy main docs — peaceiris to gh-pages root, keep_files: true (preserves /dev/)
Deploy dev docs — mike deploy main → gh-pages/dev/main/, then mike set-default main so /dev/ redirects to the moving docs from main

The main version label means “docs tracking the main branch”, distinct from frozen release snapshots like 2.9 or 3.0.

Manual release snapshots

manage-dev-docs.yml (workflow_dispatch only):

deploy-version: deploy a pinned label (e.g. 2.9) from a git tag
- Checkout workflow branch for dev-docs/ + pyproject.toml (tooling always current)
- Overlay only deeplabcut/ from the tag (API matches that release)
- mike deploy → gh-pages/dev/<version>/
delete-version: remove a version from gh-pages

Design choices worth noting

Two doc systems, one gh-pages branch — JB at root, dev docs under /dev/; peaceiris runs before mike so root deploy doesn’t wipe versioned docs
Branch vs tag split for manual deploys — modern mkdocs tooling from branch, API source from tag
No deploy on PR — only build validation; deployment happens after merge to main

deruyter92 · 2026-05-27T15:43:07Z

@C-Achard, ready for intermediate review. We should discuss limiting the documented API further to focus only on the current main API. Let's also discuss the workflows.

C-Achard · 2026-05-27T16:01:25Z

Thanks, having a look now!

C-Achard

Ok, there are a lot of comments, I'd suggest discussing this together @deruyter92, or happy to answer here if you have questions.

Thanks for adapting this!

C-Achard · 2026-05-27T15:38:30Z

+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"


Does the bot need special permissions ?

Good point, we need to add permissions for pushing to the gh-pages branch

C-Achard · 2026-05-27T16:00:59Z

Based on compat, should this be numpy instead?

[tool.ruff.lint.pydocstyle] convention = "google"

And should we add auto dosctring formatting? Some API docs render weirdly for me, I think because of styling issues in the dosctrings

I would rather stick with google, which should normally work well with mkdocs as well.

I agree that a lot of docstrings render weirdly at the moment, which is probably worth an extra PR.

C-Achard · 2026-05-27T16:01:51Z

Can we somehow avoid duplicates?

With the deploy one

yes good suggestion, this is duplicated now indeed

C-Achard · 2026-05-28T08:10:33Z

Recommend adding:

[tool.ruff.format] docstring-code-format = true

This helps make docstrings more consistent.

Warning
This is going to change a lot of files though! We could make a separate PR if preferred

Lets do it in a separate PR!

C-Achard · 2026-05-28T08:11:31Z

+              returns_multiple_items: false
+            docstring_section_style: table
+            separate_signature: true
+            line_length: 88


Suggested change

line_length: 88

line_length: 120

dosctring_style: numpy

This solves a lot of rendering oddities in parameters for me, but not all. Still, params sections render correctly with this.

Good suggestion, feel free to play around with it in this branch. I'm currently not working at it.

C-Achard · 2026-05-28T08:26:53Z

+
+copyright: "Copyright © 2026 The DeepLabCut Team"
+
+nav:


Could we put mds in a folder tree mirroring the TOC or at least grouped by topic for future extensibility?

yes we can do that, good suggestion.

C-Achard · 2026-05-28T08:37:23Z

I would recommend not adding this, I think contribution guides cover dev installation well enough.
pre-commit usage and config, CI workflows, etc, would be better topics IMO

agreed. Let's keep it in the main docs only

C-Achard · 2026-05-28T08:38:07Z

+
+## Running Top-Down Video Analysis with Existing Bounding Boxes
+
+When `deeplabcut.pose_estimation_pytorch.apis.videos.video_inference` is called with a top-down model, it is assumed that a detector snapshot is given as well to obtain bounding boxes with which to run pose estimation. It's possible that you've already obtained bounding boxes for your video (with another object detector or through some other means), and you want to reuse those bounding boxes instead of running an object detector again.


This kind of guidance is super nice

shall we add it in the main docs as well? or only dev-docs material?

C-Achard · 2026-05-28T08:42:55Z

+extra:
+  version:
+    provider: mike
+    default: main


Suggested change

extra:

version:

provider: mike

default: main

extra:

main_docs_url: "https://deeplabcut.github.io/DeepLabCut/"

version:

provider: mike

default: main

C-Achard · 2026-05-28T08:44:05Z

+nav:
+  - Get Started:


Suggested change

nav:

- Get Started:

nav:

- "← Main Documentation": "https://deeplabcut.github.io/DeepLabCut/"

- Get Started:

deruyter92 · 2026-05-28T09:58:17Z

@C-Achard: green light to play around with this branch, I am currently not working on it. Good suggestions overall!

arashsm79 and others added 7 commits May 19, 2026 14:31

docs: set up developer documentation

d8d8092

docs: add stub files for dev documentation

2b7d710

docs: add preliminary dev docs

880f72e

dev docs: fix CI build dev docs

4d3623e

dev docs: move to project root

6e39a20

dev docs: remove incomplete guides from index

a08654b

dev docs: update configuration and custom_models sections [WIP]

2709a82

C-Achard added the documentation documentation updates/comments label May 20, 2026

C-Achard assigned deruyter92 and C-Achard May 21, 2026

C-Achard added this to the Docs audit: April 2026 milestone May 21, 2026

C-Achard changed the title ~~docs [April 2026] add dev docs~~ Docs audit [April 2026]: Add dev docs May 21, 2026

C-Achard mentioned this pull request May 21, 2026

Docs audit [April 2026]: Full version #3341

Open

16 tasks

deruyter92 changed the base branch from main to cy/docs-audit-2026-toc-update May 27, 2026 08:57

deruyter92 added 2 commits May 27, 2026 13:44

dev docs: improve API formatting

78e6dde

dev docs: add mike deploy workflow for versioning

ef7c729

C-Achard force-pushed the cy/docs-audit-2026-toc-update branch from 546d24f to b52abbf Compare May 27, 2026 12:17

Base automatically changed from cy/docs-audit-2026-toc-update to docs/audit-2026 May 27, 2026 13:07

deruyter92 added 5 commits May 27, 2026 15:25

dev docs: add CI dev-docs build step (for validation)

4e0b5f0

dev docs: CI latest dev docs from main, manual dispatch for others

e6ba863

dev docs: reverse CI order (deploy main docs before dev docs)

e2e1956

dev-docs: only checkout deeplabcut module from version, not entire repo

aa1c064

dev docs: rename 'latest' to 'main' + fix mike deploy prefix

eaf049c

deruyter92 requested a review from C-Achard May 27, 2026 15:41

C-Achard reviewed May 28, 2026

View reviewed changes

C-Achard mentioned this pull request Jun 1, 2026

Documentation: format docstrings for dev docs #3353

Open

Merge branch 'docs/audit-2026' into arash/dev_docs

24a1f00


		## Running Top-Down Video Analysis with Existing Bounding Boxes

		When `deeplabcut.pose_estimation_pytorch.apis.videos.video_inference` is called with a top-down model, it is assumed that a detector snapshot is given as well to obtain bounding boxes with which to run pose estimation. It's possible that you've already obtained bounding boxes for your video (with another object detector or through some other means), and you want to reuse those bounding boxes instead of running an object detector again.

Uh oh!

Conversation

deruyter92 commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Dev docs: build & deploy approach

What gets built

CI on PRs (build only)

Auto-deploy on push to main

Manual release snapshots

Design choices worth noting

Uh oh!

deruyter92 commented May 27, 2026

Uh oh!

C-Achard commented May 27, 2026

Uh oh!

C-Achard left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deruyter92 commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

deruyter92 commented May 19, 2026 •

edited

Loading

Auto-deploy on push to `main`