Skip to content

Documentation : Update formatting of single animal guide#3315

Draft
C-Achard wants to merge 19 commits into
docs/audit-2026from
cy/docs-audit-2026-update-single-animal
Draft

Documentation : Update formatting of single animal guide#3315
C-Achard wants to merge 19 commits into
docs/audit-2026from
cy/docs-audit-2026-update-single-animal

Conversation

@C-Achard
Copy link
Copy Markdown
Collaborator

@C-Achard C-Achard commented May 7, 2026

Motivation

The single animal guide has some older formatting present that could be improved in order to help navigation in the document, and better focus the attention of users on important concepts.

Scope

Refreshes the guide's format to be more MyST-like, more consistent, and provide better navigation with a contents table and working links, as well as more bullet lists and consistent section headers throughout.

TODO

  • Finish converting images to figures with proper refs
  • Fix markdown links using []() to be proper {ref} directives.

@C-Achard C-Achard added this to the Docs audit: April 2026 milestone May 7, 2026
@C-Achard C-Achard requested a review from Copilot May 7, 2026 08:34
@C-Achard C-Achard self-assigned this May 7, 2026
@C-Achard C-Achard added enhancement New feature or request documentation documentation updates/comments labels May 7, 2026
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates the single-animal documentation to use more consistent MyST/Sphinx-friendly formatting (admonitions, images/figures, headings) and improves navigability via an in-page contents block and reorganized sections.

Changes:

  • Refactors standardDeepLabCut_UserGuide.md into a more structured MyST format (contents directive, admonitions, images-as-directives, reorganized headings/lists).
  • Updates UseOverviewGuide.md to point readers to the single-animal guide using the new target label.
  • Adds a Windows “run as administrator” admonition to the Project Manager GUI doc.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File Description
docs/UseOverviewGuide.md Updates links pointing to the single-animal guide.
docs/standardDeepLabCut_UserGuide.md Major MyST formatting refresh: contents block, directive-based images, admonitions, and section restructuring.
docs/gui/PROJECT_GUI.md Adds an {important} note about Windows admin terminal usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/UseOverviewGuide.md Outdated
Comment thread docs/UseOverviewGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
@deruyter92 deruyter92 self-requested a review May 11, 2026 14:05
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated
@deruyter92 deruyter92 self-assigned this May 18, 2026
Comment thread docs/standardDeepLabCut_UserGuide.md Outdated

The user can use the *Load Video* button to load one of the videos in the project configuration file, use the scroll
bar to navigate across the video and *Grab a Frame* (or a range of frames, as of version 2.0.5) to extract the frame(s).
bar to navigate across the video and grab a frame or a range of frames to extract the frame(s).
Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to self: the napari plugin extraction does not support ranges. Should be added.

@C-Achard
Copy link
Copy Markdown
Collaborator Author

Thanks for the further updates @deruyter92

@deruyter92 deruyter92 force-pushed the cy/docs-audit-2026-update-single-animal branch from 563710f to f3fb36a Compare May 19, 2026 11:58
Copy link
Copy Markdown
Collaborator Author

@C-Achard C-Achard left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great changes, thanks! Can't approve as it is my own PR, but looks good.

@C-Achard 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
C-Achard and others added 12 commits May 27, 2026 16:28
Improve user documentation for the GUI and CLI flows: add an important note to always run the terminal as administrator on Windows, rename and rephrase GUI/CLI headings for clarity, and break out stepwise startup instructions. Restructure the create_new_project section with a concise list of required and optional arguments, add a note explaining symbolic links and why Windows requires admin privileges, include a code example and tip block, and fix Windows path formatting. Minor wording and formatting tweaks throughout to improve readability.
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.
@C-Achard C-Achard force-pushed the cy/docs-audit-2026-update-single-animal branch from 69a1ca3 to 1b2a42b Compare May 27, 2026 14:28
Replace markdown-style links with Sphinx {ref} cross-reference roles in docs/UseOverviewGuide.md and docs/maDLC_UserGuide.md to ensure proper Sphinx rendering. Also fix a malformed bracket/URL in docs/pytorch/architectures.md for the Ye et al. citation link.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation updates/comments enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants