Migrate and update documentation to Google Doc style#395
Draft
kozlov721 wants to merge 13 commits into
Draft
Conversation
kozlov721
requested review from
conorsim,
klemen1999 and
tersekmatija
and removed request for
a team
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughAdds doc-schema validation and CI doctest steps; updates pre-commit and pyproject tooling; adds scripts to build intersphinx inventory and a comprehensive doc-schema checker; standardizes many docstrings across the codebase; small tweaks for variant alias robustness and a test fixture. ChangesDocumentation schema + tooling
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (2)
scripts/check_doc_schema.py (1)
14-14: 💤 Low valueConsider aliasing the rich print import.
The import shadows Python's builtin
♻️ Optional refactor
-from rich import print +from rich import print as rprintThen update line 242:
- print("Documentation schema check failed:", file=sys.stderr) + rprint("Documentation schema check failed:", file=sys.stderr)And line 244:
- print(f" - {error}", file=sys.stderr) + rprint(f" - {error}", file=sys.stderr)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/check_doc_schema.py` at line 14, Change the shadowing import "from rich import print" to an aliased import (e.g., "from rich import print as rich_print") and then replace uses of the builtin-shadowing print with rich_print in the places noted (the call sites currently at the locations referenced around lines where print is used, e.g., the two occurrences mentioned). Ensure any other file-scope calls that expect the builtin print remain using print or are updated to rich_print as appropriate so there is no ambiguity between builtins and the rich printer.luxonis_train/nodes/heads/transformer_segmentation_head.py (1)
74-86: ⚡ Quick winImprove Notes section formatting for readability.
The Notes section on line 84 is a single long sentence listing 5 steps. Consider reformatting it as a numbered list for better readability.
📝 Suggested formatting improvement
- Notes: - Steps: 1. Project each feature map to a channel dim of 256 using 1x1 convolutions. 2. Upsample the feature maps to 1/4 of the image size. 3. Fuse the projected feature maps through summation. 4. Apply segmentation head. 5. Upsample to original input resolution. + Notes: + Processing steps: + + 1. Project each feature map to a channel dim of 256 using 1x1 convolutions. + 2. Upsample the feature maps to 1/4 of the image size. + 3. Fuse the projected feature maps through summation. + 4. Apply segmentation head. + 5. Upsample to original input resolution.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@luxonis_train/nodes/heads/transformer_segmentation_head.py` around lines 74 - 86, Update the forward method docstring in transformer_segmentation_head.py (function forward) to reformat the Notes section into a clear numbered list instead of a single long sentence: break the five steps into separate numbered lines (1. project each feature map with 1x1 conv to 256 channels, 2. upsample to 1/4 image size, 3. fuse by summation, 4. apply segmentation head, 5. upsample to original resolution) while keeping existing descriptions and argument/return blocks intact.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/ci.yaml:
- Around line 136-183: Update the doctest CI job to harden action usage: replace
unpinned action versions used in steps named "Checkout", "Set up Python",
"Upload doctest results to Codecov", "Upload doctest coverage to Codecov", and
"Upload doctest coverage as artifact" by pinning each uses: to a specific commit
SHA (not just `@vN`) and add persist-credentials: false under the "Checkout" step;
keep the step names ("Checkout", "Set up Python", "Upload doctest results to
Codecov", "Upload doctest coverage to Codecov", "Upload doctest coverage as
artifact") and ensure the pinned SHAs correspond to the commits for
actions/checkout, actions/setup-python, codecov/test-results-action,
codecov/codecov-action, and actions/upload-artifact respectively.
In `@luxonis_train/attached_modules/losses/ctc_loss.py`:
- Line 24: The docstring incorrectly says "raw OCR labels encoded by the
attached node encoder" — update it to state that the target parameter is
provided unencoded (raw OCR labels) and will be encoded inside the forward pass
via self.node.encoder; specifically, revise the description near the target
parameter in the CTC loss docstring to mention that encoding is performed by
target = self.node.encoder(target) inside forward (or in the CTC_Loss.forward
method) so callers know to pass unencoded labels.
- Line 58: The docstring for the parameter "target" incorrectly says it's
"encoded" — update the parameter description in the CTCLoss docstring (the
target param in the class/method that calls node_encoder) to state that targets
are unencoded/raw on entry (e.g., token ids or label indices) and that they are
encoded by the node encoder at runtime (see the call to node_encoder around
where targets are passed/encoded). Ensure the wording matches the class name
CTCLoss and the method that performs encoding so readers know encoding happens
inside the implementation rather than beforehand.
In `@luxonis_train/attached_modules/losses/precision_dfl_detection_loss.py`:
- Around line 180-193: The docstring for decode_bbox is missing a proper Returns
description; update the Returns section of the decode_bbox(anchor_points:
Tensor, pred_dist: Tensor) method to clearly state that it returns the decoded
bounding boxes as a Tensor of shape [batch_size, N, 4] (or the correct dims used
in the implementation), where each 4-tuple is [x_min, y_min, x_max, y_max] or
the coordinate format used, and indicate the Tensor dtype and units if
applicable; ensure the wording matches the function behavior in decode_bbox and
replace the placeholder "Return value" with this precise description.
In `@luxonis_train/attached_modules/losses/precision_dfl_segmentation_loss.py`:
- Around line 195-206: Add a Returns section to the compute_segmentation_loss
docstring that documents the return value: a Tensor containing the total
segmentation loss for the batch (a scalar loss value), optionally noting its
shape (e.g., torch.Tensor scalar) and dtype; update the docstring immediately
after the Args block in the compute_segmentation_loss function in
precision_dfl_segmentation_loss.py so callers and docs clearly know what is
returned.
In
`@luxonis_train/attached_modules/visualizers/instance_seg_keypoint_visualizer.py`:
- Around line 24-29: The forward method in InstanceSegKeypointVisualizer has the
canvas parameters reversed relative to BaseVisualizer.run (which supplies
(target_canvas, prediction_canvas)); update the forward signature (and any
internal variable names) so the first canvas parameter is target_canvas and the
second is prediction_canvas, adjust the docstring to reflect the corrected input
order, and ensure all internal drawing calls that currently use the reversed
names (references to forward, target_canvas, prediction_canvas) are swapped
accordingly so targets are drawn on the target canvas and predictions on the
prediction canvas.
In `@luxonis_train/attached_modules/visualizers/segmentation_visualizer.py`:
- Around line 126-138: The Returns docstring is inaccurate: the function
sometimes returns a single Tensor when target is None but currently documents
tuple[Tensor, Tensor]; update the Returns section to reflect the actual return
type (e.g., Tensor | tuple[Tensor, Tensor] or tuple[Tensor, Optional[Tensor]]),
mentioning that a single Tensor is returned when target is None. Adjust the
return type wording in the docstring near the parameters (prediction_canvas,
target_canvas, predictions, target) so it matches the code path that checks
target is None and returns only the prediction visualization.
In `@luxonis_train/callbacks/gpu_stats_monitor.py`:
- Line 70: The docstring for the parameter intra_step_time in
luxonis_train.callbacks.gpu_stats_monitor (look for the GpuStatsMonitor/__init__
or method docstring that lists intra_step_time) uses "{False}" for the default;
update it to use the same backtick formatting as the other parameters
(``False``) so the default rendering is consistent with lines 71-73.
In `@luxonis_train/core/core.py`:
- Around line 707-709: The docstring for finalize_run uses old Sphinx
`@type/`@param tags; update it to the Google-style "Args:" section to match the
rest of the file—replace the `@type/`@param lines for parameters like status with
an Args: block listing each parameter name, its type, and a one-line
description, and keep the existing return/raises sections consistent with Google
style while leaving function signature and behavior unchanged.
In `@luxonis_train/nodes/heads/bisenet_head.py`:
- Line 24: The docstring license placeholders are inconsistent: class
BisenetHead (class docstring) uses "License: Unknown" while the
BisenetHead.__init__ docstring uses "License: NOT SPECIFIED"; standardize them
to a single placeholder (pick one, e.g., "License: Unknown") by updating the
license line in the BisenetHead class docstring and the BisenetHead.__init__
docstring so both use the exact same text.
In `@luxonis_train/nodes/heads/ddrnet_segmentation_head.py`:
- Around line 64-76: Update the broken URLs in the docstring Notes and See Also
sections of the DDRNet segmentation head (locate the DDRNetSegmentationHead
class or the module-level docstring in ddrnet_segmentation_head.py): remove the
stray spaces inside the GitHub URLs so "https://github.com/Deci-AI/super-
gradients/blob/master/LICENSE.md" becomes
"https://github.com/Deci-AI/super-gradients/blob/master/LICENSE.md" and
"https://github.com/Deci-AI/super-gradients/blob/master/src
/super_gradients/..." becomes
"https://github.com/Deci-AI/super-gradients/blob/master/src/super_gradients/..."
so both links work correctly.
---
Nitpick comments:
In `@luxonis_train/nodes/heads/transformer_segmentation_head.py`:
- Around line 74-86: Update the forward method docstring in
transformer_segmentation_head.py (function forward) to reformat the Notes
section into a clear numbered list instead of a single long sentence: break the
five steps into separate numbered lines (1. project each feature map with 1x1
conv to 256 channels, 2. upsample to 1/4 image size, 3. fuse by summation, 4.
apply segmentation head, 5. upsample to original resolution) while keeping
existing descriptions and argument/return blocks intact.
In `@scripts/check_doc_schema.py`:
- Line 14: Change the shadowing import "from rich import print" to an aliased
import (e.g., "from rich import print as rich_print") and then replace uses of
the builtin-shadowing print with rich_print in the places noted (the call sites
currently at the locations referenced around lines where print is used, e.g.,
the two occurrences mentioned). Ensure any other file-scope calls that expect
the builtin print remain using print or are updated to rich_print as appropriate
so there is no ambiguity between builtins and the rich printer.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d95338b2-da9e-4457-8da1-d927ddc28418
📒 Files selected for processing (142)
.github/workflows/ci.yaml.pre-commit-config.yamlluxonis_train/__main__.pyluxonis_train/assigners/__init__.pyluxonis_train/assigners/atss_assigner.pyluxonis_train/assigners/tal_assigner.pyluxonis_train/assigners/utils.pyluxonis_train/attached_modules/base_attached_module.pyluxonis_train/attached_modules/losses/adaptive_detection_loss.pyluxonis_train/attached_modules/losses/base_loss.pyluxonis_train/attached_modules/losses/bce_with_logits.pyluxonis_train/attached_modules/losses/cross_entropy.pyluxonis_train/attached_modules/losses/ctc_loss.pyluxonis_train/attached_modules/losses/efficient_keypoint_bbox_loss.pyluxonis_train/attached_modules/losses/embedding_losses.pyluxonis_train/attached_modules/losses/fomo_localization_loss.pyluxonis_train/attached_modules/losses/ohem_loss.pyluxonis_train/attached_modules/losses/precision_dfl_detection_loss.pyluxonis_train/attached_modules/losses/precision_dfl_segmentation_loss.pyluxonis_train/attached_modules/losses/reconstruction_segmentation_loss.pyluxonis_train/attached_modules/losses/sigmoid_focal_loss.pyluxonis_train/attached_modules/losses/smooth_bce_with_logits.pyluxonis_train/attached_modules/losses/softmax_focal_loss.pyluxonis_train/attached_modules/metrics/base_metric.pyluxonis_train/attached_modules/metrics/confusion_matrix/confusion_matrix.pyluxonis_train/attached_modules/metrics/confusion_matrix/detection_confusion_matrix.pyluxonis_train/attached_modules/metrics/confusion_matrix/fomo_confusion_matrix.pyluxonis_train/attached_modules/metrics/confusion_matrix/instance_segmentation_confusion_matrix.pyluxonis_train/attached_modules/metrics/confusion_matrix/recognition_confusion_matrix.pyluxonis_train/attached_modules/metrics/confusion_matrix/utils.pyluxonis_train/attached_modules/metrics/dice_coefficient.pyluxonis_train/attached_modules/metrics/embedding_metrics.pyluxonis_train/attached_modules/metrics/mean_average_precision/mean_average_precision.pyluxonis_train/attached_modules/metrics/mean_average_precision/mean_average_precision_bbox.pyluxonis_train/attached_modules/metrics/mean_average_precision/mean_average_precision_keypoints.pyluxonis_train/attached_modules/metrics/mean_average_precision/mean_average_precision_segmentation.pyluxonis_train/attached_modules/metrics/mean_iou.pyluxonis_train/attached_modules/metrics/object_keypoint_similarity.pyluxonis_train/attached_modules/metrics/ocr_accuracy.pyluxonis_train/attached_modules/metrics/torchmetrics.pyluxonis_train/attached_modules/metrics/utils.pyluxonis_train/attached_modules/visualizers/base_visualizer.pyluxonis_train/attached_modules/visualizers/bbox_visualizer.pyluxonis_train/attached_modules/visualizers/classification_visualizer.pyluxonis_train/attached_modules/visualizers/embeddings_visualizer.pyluxonis_train/attached_modules/visualizers/fomo_visualizer.pyluxonis_train/attached_modules/visualizers/instance_seg_keypoint_visualizer.pyluxonis_train/attached_modules/visualizers/instance_segmentation_visualizer.pyluxonis_train/attached_modules/visualizers/keypoint_visualizer.pyluxonis_train/attached_modules/visualizers/ocr_visualizer.pyluxonis_train/attached_modules/visualizers/segmentation_visualizer.pyluxonis_train/attached_modules/visualizers/utils.pyluxonis_train/callbacks/archive_on_train_end.pyluxonis_train/callbacks/convert_on_train_end.pyluxonis_train/callbacks/ema.pyluxonis_train/callbacks/export_on_train_end.pyluxonis_train/callbacks/gpu_stats_monitor.pyluxonis_train/callbacks/graceful_interrupt.pyluxonis_train/callbacks/gradcam_visualizer.pyluxonis_train/callbacks/luxonis_progress_bar.pyluxonis_train/callbacks/metadata_logger.pyluxonis_train/callbacks/test_on_train_end.pyluxonis_train/callbacks/training_manager.pyluxonis_train/callbacks/training_progress_callback.pyluxonis_train/callbacks/upload_checkpoint.pyluxonis_train/config/config.pyluxonis_train/config/predefined_models/base_predefined_model.pyluxonis_train/core/core.pyluxonis_train/core/utils/annotate_utils.pyluxonis_train/core/utils/archive_utils.pyluxonis_train/core/utils/export_utils.pyluxonis_train/core/utils/infer_utils.pyluxonis_train/core/utils/train_utils.pyluxonis_train/lightning/luxonis_lightning.pyluxonis_train/lightning/utils.pyluxonis_train/loaders/base_loader.pyluxonis_train/loaders/dummy_loader.pyluxonis_train/loaders/luxonis_loader_torch.pyluxonis_train/loaders/luxonis_perlin_loader_torch.pyluxonis_train/loaders/perlin.pyluxonis_train/nodes/backbones/contextspatial.pyluxonis_train/nodes/backbones/ddrnet/blocks.pyluxonis_train/nodes/backbones/ddrnet/ddrnet.pyluxonis_train/nodes/backbones/dinov3/dinov3.pyluxonis_train/nodes/backbones/efficientnet.pyluxonis_train/nodes/backbones/efficientrep/efficientrep.pyluxonis_train/nodes/backbones/efficientvit/blocks.pyluxonis_train/nodes/backbones/efficientvit/efficientvit.pyluxonis_train/nodes/backbones/ghostfacenet/ghostfacenet.pyluxonis_train/nodes/backbones/micronet/blocks.pyluxonis_train/nodes/backbones/micronet/micronet.pyluxonis_train/nodes/backbones/mobilenetv2.pyluxonis_train/nodes/backbones/mobileone/mobileone.pyluxonis_train/nodes/backbones/pplcnet_v3/pplcnet_v3.pyluxonis_train/nodes/backbones/recsubnet/recsubnet.pyluxonis_train/nodes/backbones/repvgg/repvgg.pyluxonis_train/nodes/backbones/resnet.pyluxonis_train/nodes/backbones/rexnetv1.pyluxonis_train/nodes/base_node.pyluxonis_train/nodes/blocks/blocks.pyluxonis_train/nodes/blocks/reparametrizable.pyluxonis_train/nodes/blocks/resnet.pyluxonis_train/nodes/blocks/unet.pyluxonis_train/nodes/blocks/utils.pyluxonis_train/nodes/heads/base_detection_head.pyluxonis_train/nodes/heads/base_head.pyluxonis_train/nodes/heads/bisenet_head.pyluxonis_train/nodes/heads/classification_head.pyluxonis_train/nodes/heads/ddrnet_segmentation_head.pyluxonis_train/nodes/heads/discsubnet_head/discsubnet_head.pyluxonis_train/nodes/heads/efficient_bbox_head.pyluxonis_train/nodes/heads/efficient_keypoint_bbox_head.pyluxonis_train/nodes/heads/fomo_head.pyluxonis_train/nodes/heads/ghostfacenet_head.pyluxonis_train/nodes/heads/ocr_ctc_head.pyluxonis_train/nodes/heads/precision_bbox_head.pyluxonis_train/nodes/heads/precision_seg_bbox_head.pyluxonis_train/nodes/heads/segmentation_head.pyluxonis_train/nodes/heads/transformer_classification_head.pyluxonis_train/nodes/heads/transformer_segmentation_head.pyluxonis_train/nodes/necks/reppan_neck/blocks.pyluxonis_train/nodes/necks/reppan_neck/reppan_neck.pyluxonis_train/nodes/necks/svtr_neck/svtr_neck.pyluxonis_train/registry.pyluxonis_train/strategies/triple_lr_sgd.pyluxonis_train/tasks.pyluxonis_train/typing.pyluxonis_train/utils/annotation.pyluxonis_train/utils/boundingbox.pyluxonis_train/utils/dataset_metadata.pyluxonis_train/utils/general.pyluxonis_train/utils/keypoints.pyluxonis_train/utils/ocr.pyluxonis_train/utils/tracker.pyluxonis_train/variants.pypyproject.tomlscripts/check_doc_schema.pytests/integration/test_bump_opset_version.pytests/integration/test_export_unique_identifiers.pytests/integration/test_overfit_batches.pytests/integration/test_overfit_convergence.pytests/unittests/test_callbacks/test_ema.py
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
1 participant
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
Migrate
luxonis_trainAPI documentation to Google-style docstrings and normalize node/attached-module documentation into a consistent, parseable schema for future docs frontend work.This also preserves node variant information in human-readable nested lists so pydoctor output can later be consumed structurally without relying on raw Python dictionaries or compact encoded strings.
Specification
luxonis_trainto Google style compatible with pydoctor.MetadataProvenanceVariantsfor nodesPrediction format,Target format, andFormulafor attached modulesUnknown,Internal,None, andProject licensewhere source/license/task details are unclear or absent.Dependencies & Potential Impact
No runtime dependency changes are expected.
Potential impact is limited to documentation generation, pre-commit behavior, and pydoctor parsing. The new local pre-commit hook may block future changes that add or modify node/attached-module docs without the required schema.
AI Usage
Assisted-by: OpenAI Codex:gpt-5
Submitted code was reviewed by a human: YES
The author is taking the responsibility for the contribution: YES
Summary by CodeRabbit
Documentation
Tests
Chores