Docs audit [April 2026]: update multi-animal guide - #3335

Convert the single-animal user guide to MyST-friendly markdown and improve layout and clarity. Changes include: add a table-of-contents directive; replace raw HTML <img>/<p> blocks with MyST image directives and metadata; introduce admonitions (important/note/caution/hint) for critical points; restructure the project directory section into bulleted lists and an ASCII tree; clarify Windows path guidance and config.yaml parameter notes; normalize API Docs headings and other formatting fixes. These are documentation/formatting updates to improve rendering and readability—no functional code changes.

Update documentation for the single-animal user guide: convert local link refs to file:single-animal-userguide, fix napari link formatting, and reorganize/clarify many sections in standardDeepLabCut_UserGuide.md. Added consistent subsection headings (Overview, Code example, Output, etc.), separators, code block language annotations, a schematic of the training dataset layout, and improved wording/indentation for lists and examples. Also updated UseOverviewGuide.md to point to the revised single-animal guide. These changes improve readability, provide clearer examples, and make the workflow steps and outputs easier to follow.

Minor documentation cleanup in docs/standardDeepLabCut_UserGuide.md: split the conda activation into its own numbered step, simplify wording and line breaks for clarity, and remove bold all-caps headings (OVERVIEW and MODEL COMPARISON) in favor of normal sentences. Purely editorial changes; no functional code changes.

Reorganize the project directory section in the user guide: move the sentence about where outputs are stored to follow the directory tree block and adjust list numbering for the subdirectory descriptions for clarity. Replace Markdown-style links to the napari-deeplabcut docs with Sphinx {ref} roles in two places and clean up minor whitespace/formatting.

Miscellaneous documentation fixes and clarifications across the user guide:
- Grammar/wording fixes (e.g. "training and testing set", other minor edits).
- Rename config option reference: numframes2extract -> numframes2pick.
- Update napari-deeplabcut docs reference to RST cross-reference style.
- Rework Optional labels section for clearer phrasing and line breaks.
- Adjust networks paragraph spacing and wording.
- Reformat dynamic-cropping docs: use triple-quoted string, change "triple" -> "tuple", correct "detectiontreshold" -> "detectionthreshold", and move explanatory text outside the code block for readability.
- Update Filter Pose Data: note output used by create_labeled_video (was create_labeled_data) and plot trajectories.
- Minor improvements to Plot Trajectories section wording and spacing.
- Clarify SkeletonBuilder usage: call deeplabcut.SkeletonBuilder(config_path) and explain config_path.
These edits are documentation-only and improve readability, accuracy, and consistency.

Rewrite and reorganize project subdirectory documentation for clarity: convert prose into numbered sections for dlc-models/dlc-models-pytorch, labeled-data, training-datasets, and videos; clarify iteration/shuffle/train/test structure, YAML config files, and checkpoint usage; note copy_videos behavior (default False). Update napari labeling section to use a hint block linking to napari docs and remove the inline HOT KEYS block (left commented out). Minor wording tweaks for the optional-labels and label-checking guidance.

Apply editorial fixes to the standard DeepLabCut user guide: correct spelling (e.g., "docstrings"), standardize capitalization for PyTorch and TensorFlow, unify dataset/data set usage, fix punctuation and spacing (e.g., video path, SkeletonBuilder call), and normalize list capitalization. These changes improve readability and consistency across the documentation.

…gle-animal)

…aders accordingly

* Update custom.css

* Refine workflow dropdown styles and colors

Update docs/_static/custom.css to adjust dark-theme variables and overhaul workflow dropdown styling. Changed single/multi-animal background variables, replaced old title-prefix approach with CSS-generated emoji titles, and hid sphinx-design's no-title icon. Apply consistent header/body color variables for sd-card dropdowns, keep text/chevron colors stable, and disable pydata's hover darken/lighten effect to prevent color shifts on focus/hover. These changes ensure consistent appearance and correct application of border/background styles overridden by pydata.

…ng details to separate doc.

Update documentation to use MyST's :class-container for dropdown directives (previous :class usages updated in docs/_static/custom.css and docs/main-workflows/user-guide.md). Also correct the YAML frontmatter formatting in user-guide.md (expand inline metadata into a proper YAML block). These changes align docs with current MyST/Sphinx directive syntax and fix frontmatter parsing.

Adjust multi-animal CSS variables in light and dark themes to be more distinct from hint/tip boxes. Updated --multi-animal-border to #57c4be, --multi-animal-bg to #e8f8f7, --multi-animal-title-bg to #21a197, and --multi-animal-title-text to #000000 in both themes.

Editorial and formatting updates to the main user guide and added an updated multi-animal figure. Changes include: clarified multi-animal workflow wording, strengthened guidance (emphasis on recommended options), reworked admonitions (hint/danger/tip), improved paragraph flow and bullet structure, clarified frame selection methods and recommendations, updated examples and GUI notes, refined training/evaluation/tracking explanations, and replaced the multi-animal figure reference with docs/images/box1-multi-rec.png (recolored for new CSS). Miscellaneous typography and markup fixes (code blocks, YAML/file references, and symbol styling) to improve readability.

Improve rendering and correctness in docs/main-workflows/user-guide.md: change admonition key to `class-container`, update dropdown/admonition syntax, fix code block languages (python -> yaml/text), correct example function parameter (`config` -> `config_path`), adjust heading capitalization and list formatting. These changes ensure examples render correctly and the docs reflect the actual API usage.

Add single- and multi-animal quick-start pages to the Main workflows overview in _toc.yml and substantially rewrite both quick-start docs. single_animal_quick_guide.md was reorganized into a clear step-by-step workflow (create project, configure, extract/label frames, create dataset, train/evaluate, analyze/filter/plot/create videos) with concrete Python examples, notes, and tips (use absolute paths, no spaces in body-part names). tutorial_maDLC.md was refactored into a multi-animal overview with GUI and Python workflows, clearer config guidance for multi-animal fields, extraction/annotation/checking steps, separate training engine examples (PyTorch/TensorFlow), and explicit tracking steps (analyze, convert detections, stitch tracklets, create labeled videos) plus helpful notes. Overall improvements focus on clarity, concrete examples, and actionable tips for users.

Remove the parenthetical reference to www.deeplabcut.org and merge the broken sentence in the TensorFlow Engine augmentation section to improve readability and flow. No functional changes; content about available loaders remains the same.

…-audit-2026-update-ma-guide