Docs versioning: Add glob support, better validation and reporting - #3278
Merged
Conversation
Normalize CLI target specs (handle Windows/backslashes, ./, absolute paths) and classify them as file/dir/glob. Implement matching logic and validation (report matched files and unmatched selectors, return rc=2 on unmatched), and apply target specs in scan/update. Add helpers (normalize_target_spec, compile_target_specs, validate_requested_targets, print_target_match_summary, iter_scan_candidate_paths) and adjust main argument help. Update tests to cover directory, glob, Windows-style paths, and CLI reporting.
C-Achard
added
enhancement
3 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Extends the tools/docs_and_notebooks_check.py CLI “versioning/check” tool so --targets can accept repo-relative files, directories, and glob patterns, with early validation and user-facing reporting of what will be scanned.
Changes:
- Added target normalization + matching (file/dir/glob) and integrated it into scanning.
- Added
--targetsvalidation/reporting inmain()(print matched files; rc=2 when any selector matches nothing). - Expanded tests to cover directory/glob selectors, Windows-style separators, and CLI output/return code behavior.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| tools/docs_and_notebooks_check.py | Adds target normalization/matching helpers, applies them in scanning, and validates/prints --targets matches in CLI. |
| tests/tools/docs_and_notebooks_checks/test_check_contracts.py | Adds contract tests for directory/glob target support, unmatched target reporting, and main() output/rc behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Treat target specs that fail normalization as kind "invalid" so they are not silently ignored. compile_target_specs now appends invalid specs, target_spec_matches_path returns False for invalid kinds, and validate_requested_targets records invalid raw selectors as unmatched (and safely iterates when specs may be None). This ensures malformed or non-normalizable CLI selectors are reported back to the user rather than dropped.
Introduce shared pytest fixtures (repo, cfg) and import Callable to reduce repetition of tmp_path/git init logic across tests. Refactor many tests to use the new fixtures and ToolConfig factory, and add/adjust tests covering target validation and scanning edge cases (several validate_requested_targets variations, scan_files with invalid only-targets, and main returning 2 for invalid selector). Overall this centralizes repo/config setup and adds coverage for target handling behavior.
Expand and clarify the --targets argument help strings in tools/docs_and_notebooks_check.py for the update and normalize subcommands. The updated messages document that --targets accepts exact files, directories, and glob patterns (with examples) and note that both '/' and '\\' path separators are accepted. This is a documentation-only change to improve user guidance; no functional behavior is altered.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…bCut/DeepLabCut into cy/docs-versioning-tweaks
…m/DeepLabCut/DeepLabCut into cy/docs-versioning-tweaks" This reverts commit 46fdb04, reversing changes made to 6d3b1be.
Introduce TypedDict-based types for FileKind and TargetSpec (with TargetKind) and tighten type annotations across functions (compile_target_specs, target_spec_matches_path, target_matches). Replace PurePosixPath-based glob matching with fnmatch.fnmatchcase only to ensure consistent, shell-style pattern behavior across platforms and remove unused imports. Minor cleanups: import TypedDict and update variable type hints for better static checking and readability.
C-Achard
marked this pull request as ready for review
April 10, 2026 10:03
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.
Purpose
The docs & notebook versioning tool currently does not support small QoL features such as glob matching, early exit when no files were matched in --targets, and listing which files it ran on.
This PR aims to extend the file to address these points and make it more comfortable to use.
Changes