Refactor#106
Merged
Merged
Conversation
Owner
Hendrik-code
commented
May 26, 2026
Hendrik-code
commented
- added setup for linting to force google-style docstrings
- added mising docstrings and missing type annotations everywhere
- added a README for every folder and API reference files
- added toolbox documentation via MkDocs + ReadTheDocs
- Add CLAUDE.md with build commands, architecture overview, and key class descriptions - Enable Google-style docstring (D rules) and return-type annotation (ANN201) checking in ruff - Add pydocstyle convention = google config section - Add docs dependency group (mkdocs, mkdocs-material, mkdocstrings) - Add per-file ruff ignores for unit_tests/ and TPTBox/tests/ directories - Fix import sort order in speedtest_panoptica.py (I001) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ughout Add docstrings to all public functions, methods, and classes previously missing them across the entire TPTBox codebase (~350 additions, reaching ~80% coverage). Add return-type annotations to all ANN201 violations. Also add D417 to ruff ignore (arg-level documentation is aspirational). Files touched: nii_wrapper, bids_files, poi, np_utils, vert_constants, nii_wrapper_math, nii_poi_abstract, all poi_fun modules, spine snapshot/spinestats, registration (rigid/deformable/deepali), segmentation (spineps/vibeseg/nnunet), mesh3D, stitching, logger, dicom, and core internal helpers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add a README.md to each sub-package documenting its purpose, key classes/functions with one-line descriptions, and minimal usage examples. Folders covered: core, core/poi_fun, logger, mesh3D, registration, segmentation, spine, spine/snapshot2D, spine/spinestats, stitching. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- mkdocs.yml: Material theme site with mkdocstrings (Google style, show_source) and full nav covering all sub-packages - .readthedocs.yml: ReadTheDocs v2 config pointing to mkdocs.yml, Python 3.12, installs package with docs extras - .github/workflows/docs.yml: CI job that builds docs on every push/PR to main - docs/: landing page, getting-started guide, and 12 API reference pages (one per sub-package) using mkdocstrings ::: directives Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Hendrik-code
added
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR is a broad refactor focused on standardizing documentation (Google-style docstrings) and type annotations across the TPTBox codebase, and introducing an MkDocs/ReadTheDocs documentation site with per-module READMEs and API reference pages.
Changes:
- Added/standardized Google-style docstrings and type annotations across core, segmentation, registration, stitching, spine, and mesh modules.
- Introduced MkDocs configuration + API reference pages and CI/RTD configuration for building docs.
- Added module-level README files and a speedtest script under
TPTBox/tests/speedtests.
Reviewed changes
Copilot reviewed 104 out of 104 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| unit_tests/test_nputils.py | Minor docstring formatting change in tests. |
| TPTBox/tests/speedtests/speedtest_panoptica.py | Adds a standalone speedtest script for array sanity checking. |
| TPTBox/stitching/stitching_tools.py | Adds typing/docstrings for stitching helpers and wrapper API. |
| TPTBox/stitching/README.md | Adds stitching module README and small API summary. |
| TPTBox/spine/spinestats/README.md | Adds spinestats README describing modules and key functions. |
| TPTBox/spine/spinestats/make_endplate.py | Adds docstrings/typing to endplate extraction utilities. |
| TPTBox/spine/spinestats/ivd_pois.py | Adds docstrings/typing to IVD POI generation pipeline. |
| TPTBox/spine/spinestats/distances.py | Improves docstrings/typing for distance computation helpers. |
| TPTBox/spine/spinestats/body_quadrants.py | Adds typing/docstring adjustments and imports for quadrants. |
| TPTBox/spine/snapshot2D/README.md | Adds README for 2D snapshot subsystem. |
| TPTBox/spine/README.md | Adds top-level spine module README and example usage. |
| TPTBox/segmentation/VibeSeg/vibeseg.py | Adds typing/docstrings and TYPE_CHECKING imports for segmentation wrappers. |
| TPTBox/segmentation/VibeSeg/inference_nnunet.py | Adds typing/docstrings for nnU-Net inference and helpers. |
| TPTBox/segmentation/VibeSeg/auto_download.py | Adds typing/docstrings for weight download + config helpers. |
| TPTBox/segmentation/spineps.py | Adds typing/docstrings for SPINEPS integration functions. |
| TPTBox/segmentation/README.md | Adds segmentation module README with public API overview. |
| TPTBox/segmentation/nnUnet_utils/sliding_window_prediction.py | Adds docstrings for sliding-window helpers. |
| TPTBox/segmentation/nnUnet_utils/inference_api.py | Adds typing/docstrings for inference entry points and utilities. |
| TPTBox/segmentation/nnUnet_utils/get_network_from_plans.py | Adds return typing and docstring cleanup. |
| TPTBox/segmentation/nnUnet_utils/export_prediction.py | Adds typing/docstrings for exporting logits/segmentations. |
| TPTBox/segmentation/nnUnet_utils/default_preprocessor.py | Adds class/function docstrings and type annotations. |
| TPTBox/segmentation/nnUnet_utils/data_iterators.py | Adds docstrings/typing for preprocessing adapter + one-hot conversion. |
| TPTBox/segmentation/_deface.py | Compresses/normalizes docstrings for defacing helpers. |
| TPTBox/registration/script_ax2sag.py | Adds typing/docstrings and refactors buffer update logic. |
| TPTBox/registration/README.md | Adds registration module README and public API overview. |
| TPTBox/registration/_ridged_intensity/register.py | Adds typing/docstrings and improves context manager typing. |
| TPTBox/registration/_ridged_intensity/affine_deepali.py | Docstring cleanup for COM and loss helpers. |
| TPTBox/registration/_deformable/multilabel_segmentation.py | Docstring/typing updates for Template_Registration methods. |
| TPTBox/registration/_deformable/grid_search.py | Adds typing/docstrings for reproducibility and grid search. |
| TPTBox/registration/_deformable/deformable_reg.py | Docstring cleanup for deformable registration and tests. |
| TPTBox/registration/_deformable/deformable_reg_old.py | Docstring cleanup for legacy deformable registration. |
| TPTBox/registration/_deformable/_grid_search_vert.py | Minor docstring punctuation fix. |
| TPTBox/registration/_deformable/_deepali/optim.py | Docstring cleanup for least-squares slope helper. |
| TPTBox/registration/_deformable/_deepali/metrics.py | Docstring cleanup for Dice/Jacobian metrics. |
| TPTBox/registration/_deepali/deepali_trainer.py | Docstring cleanup for trainer init. |
| TPTBox/registration/_deepali/deepali_model.py | Adds typing/docstrings to deepali registration utilities. |
| TPTBox/registration/_deepali/_utils.py | Adds typing/docstrings to deepali utility helpers. |
| TPTBox/registration/_deepali/_hooks.py | Minor whitespace cleanup in hook function. |
| TPTBox/mesh3D/snapshot3D.py | Adds typing/docstrings for rendering and VTK helper functions. |
| TPTBox/mesh3D/README.md | Adds mesh3D module README and example. |
| TPTBox/mesh3D/mesh.py | Adds typing/docstrings to mesh wrapper classes. |
| TPTBox/mesh3D/mesh_colors.py | Adds typing/docstrings for color utilities and palette. |
| TPTBox/mesh3D/html_preview.py | Adds typing/docstrings for HTML preview helpers. |
| TPTBox/logger/README.md | Adds logger module README and usage example. |
| TPTBox/logger/log_constants.py | Adds typing/docstrings for log formatting helpers. |
| TPTBox/core/sitk_utils.py | Adds typing/docstrings for SimpleITK/NIfTI conversion utilities. |
| TPTBox/core/README.md | Adds core package README explaining primary abstractions. |
| TPTBox/core/poi_fun/vertebra_pois_non_centroids.py | Adds typing/docstrings to POI pipeline helpers and strategies. |
| TPTBox/core/poi_fun/vertebra_direction.py | Adds typing/docstrings for direction/vector helpers. |
| TPTBox/core/poi_fun/strategies.py | Adds typing/docstrings for POI computation strategies. |
| TPTBox/core/poi_fun/README.md | Adds internal POI strategies package README. |
| TPTBox/core/poi_fun/poi_global.py | Adds typing/docstrings for global POI coordinate container. |
| TPTBox/core/poi_fun/pixel_based_point_finder.py | Adds typing/docstrings for pixel-level POI helper functions. |
| TPTBox/core/poi_fun/_help.py | Adds typing/docstrings for POI helper utilities. |
| TPTBox/core/internal/slicer_nrrd.py | Adds typing/docstrings and small refactor in writer loop. |
| TPTBox/core/internal/nii_help.py | Adds typing/docstrings for secure save and resampling helper. |
| TPTBox/core/internal/deep_learning_utils.py | Adds typing/docstring for device selection helper. |
| TPTBox/core/internal/ants_load.py | Adds typing/docstrings for ANTs↔NiBabel conversion helpers. |
| TPTBox/core/dicom/nii2dicom.py | Adds typing/docstrings for NIfTI→DICOM conversion utilities. |
| TPTBox/core/dicom/fix_brocken.py | Adds typing/docstrings to dataset repair helpers. |
| TPTBox/core/dicom/dicom2nii_utils.py | Adds typing/docstrings for DICOM metadata/json utilities. |
| TPTBox/core/dicom/dicom_header_to_keys.py | Adds typing/docstrings for DICOM→BIDS key extraction. |
| TPTBox/core/compat.py | Adds typing/docstring for zip_strict. |
| TPTBox/core/bids_constants.py | Moves/duplicates “Split” key comment for BIDS entity mapping. |
| pyproject.toml | Adds docs dependency group and Ruff docstring/type rules. |
| mkdocs.yml | Adds MkDocs Material + mkdocstrings configuration and nav. |
| docs/index.md | Adds documentation home page content. |
| docs/getting-started.md | Adds installation, concepts, and docs build instructions. |
| docs/api/vert_constants.md | Adds mkdocstrings API page for vertebra constants. |
| docs/api/stitching.md | Adds mkdocstrings API page for stitching. |
| docs/api/spine.md | Adds mkdocstrings API page for spine submodules. |
| docs/api/segmentation.md | Adds mkdocstrings API page for segmentation module. |
| docs/api/registration.md | Adds mkdocstrings API page for registration module. |
| docs/api/poi.md | Adds mkdocstrings API page for POI types/helpers. |
| docs/api/poi_fun.md | Adds mkdocstrings API page for POI strategy internals. |
| docs/api/np_utils.md | Adds mkdocstrings API page for NumPy utilities. |
| docs/api/nii.md | Adds mkdocstrings API page for NII wrapper. |
| docs/api/mesh3d.md | Adds mkdocstrings API page for mesh3D utilities. |
| docs/api/logger.md | Adds mkdocstrings API page for logger utilities. |
| docs/api/bids.md | Adds mkdocstrings API page for BIDS navigation/types. |
| .readthedocs.yml | Adds RTD configuration for MkDocs builds. |
| .github/workflows/docs.yml | Adds GitHub Actions workflow to build docs in CI. |
Comments suppressed due to low confidence (1)
TPTBox/stitching/stitching_tools.py:77
- If
chunk_infois not incut, this logs an error but then continues and will raise aKeyErroratcut[chunk_info]. Consider raising aValueError(or returning early) immediately after the validation failure so the error is explicit and consistent.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
38
to
40
| with open(buffer_path, "rb") as f: | ||
| registration_buffer = pickle.load(f) if Path(buffer_path).exists() else {} | ||
| new_reg_buffer = {} |
Comment on lines
+11
to
+16
| python: | ||
| install: | ||
| - method: pip | ||
| path: . | ||
| extra_requirements: | ||
| - docs |
Comment on lines
13
to
+16
| def stitching( | ||
| bids_files: list[BIDS_FILE | NII | str | Path] | list, | ||
| out: BIDS_FILE | str | Path, | ||
| is_seg=False, | ||
| is_seg: bool = False, |
robert-graf
reviewed
May 26, 2026
Owner
Author
There was a problem hiding this comment.
oh shit the ai comitted this accidentially. will remove it.
Merge introduced new functions and a renamed parameter that broke ruff: - dicom_extract.py: rename parameter hunk → chunk (was chunk in body, causing F821 undefined name + ARG001 unused arg) - dicom_extract.py: add docstring + return type to dicom_to_nifti_multiframe_2d - elastic_deform.py (new file): fix D212/D415 docstring format, add docstrings and return types for pad() and get_random_deform_parameter() - nii_wrapper.py: add docstring + return types for from_deepali, erode_msk_euclid, dilate_msk_euclid - np_utils.py: fix D205/D415 and add return types for np_erode_msk_euclid, np_dilate_msk_euclid - vert_constants.py: add docstring + return type for Full_Body_Instance.feet - log_file.py: add docstrings for warning() and error() methods Fix ReadTheDocs docs build: extra_requirements=[docs] requires a pip extra in pyproject.toml, but docs is only a Poetry optional group. Switch to build.jobs.post_install to install mkdocs packages directly instead. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.