docs: add NumPy-style docstrings for ReadTheDocs by oliveira-caio · Pull Request #96 · sensorium-competition/experanto

oliveira-caio · 2026-01-25T18:28:17Z

Summary

Add comprehensive NumPy-style docstrings to all public classes and functions to make it compatible with ReadTheDocs
Configure Sphinx with autodoc, napoleon, and autosummary for API documentation
Restructure API reference to generate separate pages per class/function
Create dedicated configuration page with embedded default.yaml and option descriptions
Update README with features, quick start examples, and documentation links

Changes

Docstrings

experiment.py: Experiment class, interpolate(), get_valid_range()
datasets.py: ChunkDataset class and methods
dataloaders.py: get_multisession_dataloader(), get_multisession_concat_dataloader()
interpolators.py: All interpolator classes (Interpolator, SequenceInterpolator, ScreenInterpolator, etc.)
intervals.py: TimeInterval class and interval functions
utils.py: LongCycler, ShortCycler, FastSessionDataLoader, SessionBatchSampler, etc.

Documentation Structure

Add autosummary extension for per-class/function pages
Create custom class template for detailed documentation
Move configuration to dedicated page with full default.yaml content
Rename API sections to avoid duplicate sidebar entries

README

Add features section
Add quick start code examples
Link to Read the Docs documentation

Add extensions for autodoc, napoleon, mathjax, intersphinx, and viewcode. Configure napoleon for NumPy-style docstrings with math rendering support and cross-references to Python, NumPy, SciPy, and PyTorch documentation.

- Add autodoc_mock_imports for heavy dependencies (torch, numpy, etc.) - Create api.rst with single-page API reference for all modules - Update index.rst to include API Reference section

Document package architecture, class relationships, data flow, potential bugs, and docstring requirements with priority levels.

- experiment.py: Experiment class, interpolate, get_valid_range - datasets.py: ChunkDataset class, __getitem__ - dataloaders.py: get_multisession_dataloader, get_multisession_concat_dataloader - configs.py: module-level docstring with exports documentation

- Create _static directory to fix warning - Fix initialize_statistics, initialize_transforms docstrings (datasets.py) - Fix get_screen_sample_mask_from_meta_conditions docstring (datasets.py) - Fix get_full_valid_sample_times docstring (datasets.py) - Fix add_behavior_as_channels docstring (utils.py) - Remove duplicate device_names property docstring (experiment.py)

interpolators.py: - Interpolator base class and factory method - SequenceInterpolator with linear interpolation math - ScreenInterpolator for visual stimuli - PhaseShiftedSequenceInterpolator - ScreenTrial and subclasses (ImageTrial, VideoTrial, BlankTrial) intervals.py: - TimeInterval class - All interval manipulation functions utils.py: - LongCycler, ShortCycler - FastSessionDataLoader with full parameter documentation

Add extensions for autodoc, napoleon, mathjax, intersphinx, and viewcode. Configure napoleon for NumPy-style docstrings with math rendering support and cross-references to Python, NumPy, SciPy, and PyTorch documentation.

- Add autodoc_mock_imports for heavy dependencies (torch, numpy, etc.) - Create api.rst with single-page API reference for all modules - Update index.rst to include API Reference section

Document package architecture, class relationships, data flow, potential bugs, and docstring requirements with priority levels.

- experiment.py: Experiment class, interpolate, get_valid_range - datasets.py: ChunkDataset class, __getitem__ - dataloaders.py: get_multisession_dataloader, get_multisession_concat_dataloader - configs.py: module-level docstring with exports documentation

- Create _static directory to fix warning - Fix initialize_statistics, initialize_transforms docstrings (datasets.py) - Fix get_screen_sample_mask_from_meta_conditions docstring (datasets.py) - Fix get_full_valid_sample_times docstring (datasets.py) - Fix add_behavior_as_channels docstring (utils.py) - Remove duplicate device_names property docstring (experiment.py)

interpolators.py: - Interpolator base class and factory method - SequenceInterpolator with linear interpolation math - ScreenInterpolator for visual stimuli - PhaseShiftedSequenceInterpolator - ScreenTrial and subclasses (ImageTrial, VideoTrial, BlankTrial) intervals.py: - TimeInterval class - All interval manipulation functions utils.py: - LongCycler, ShortCycler - FastSessionDataLoader with full parameter documentation

…o/experanto into claude/add-docstrings-KhA9Q

- datasets.py: get_data_key_from_root_folder - interpolators.py: rescale_frame - utils.py: SessionBatchSampler.__init__, SessionSpecificSampler.__init__

- Add sphinx.ext.autosummary extension - Create custom class template for detailed docs - Reorganize api.rst with autosummary tables - Each class/function now gets its own page

- Create configuration.rst with full default.yaml embedded - Add documentation for all configuration options - Update index.rst to include configuration page

- Add features section highlighting key capabilities - Include quick start examples for Experiment and DataLoader - Add configuration snippet and documentation links - Add contributing, license, and citation sections

gitnotebooks · 2026-01-25T18:28:20Z

Review these changes at https://app.gitnotebooks.com/sensorium-competition/experanto/pull/96

Copilot

Pull request overview

Adds NumPy-style docstrings and a Sphinx/ReadTheDocs documentation pipeline to generate API reference pages automatically.

Changes:

Added/expanded NumPy-style docstrings across core modules (datasets, interpolators, experiment, utils, intervals, dataloaders).
Added Sphinx configuration (autodoc/napoleon/autosummary) plus API/configuration pages and a custom autosummary class template.
Updated README with features, quick start, and documentation links; ignored generated API docs output in .gitignore.

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
experanto/utils.py	Updates docstrings for utilities and cyclers; minor formatting changes.
experanto/intervals.py	Adds docstrings and corrects some return type annotations for interval utilities.
experanto/interpolators.py	Adds comprehensive class/method docstrings; minor typing fix for `rescale_size`.
experanto/experiment.py	Adds class/method docstrings for the main `Experiment` interface.
experanto/datasets.py	Adds a full NumPy-style class docstring and method docstrings for `ChunkDataset`.
experanto/dataloaders.py	Adds docstrings and examples for multi-session dataloader helpers.
experanto/configs.py	Adds module docstring describing exported default config constants.
docs/source/index.rst	Cleans up wording and adds API Reference toctree entries.
docs/source/configuration.rst	New docs page describing configuration options and embedding default YAML.
docs/source/conf.py	Enables Sphinx extensions and configures autodoc/napoleon/autosummary + mocks.
docs/source/api.rst	New autosummary-driven API reference index.
docs/source/_templates/custom-class-template.rst	New autosummary template to generate per-class pages with methods/attributes.
docs/source/_static/.gitkeep	Keeps `_static/` directory tracked.
README.md	Adds features, quick start examples, and RTD links.
.gitignore	Ignores Sphinx autosummary generated output directory.

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

README.md

experanto/experiment.py

experanto/datasets.py

reneburghardt

Really nice stuff @oliveira-caio

experanto/interpolators.py

docs/source/api.rst

experanto/datasets.py

experanto/interpolators.py

- Add configuration options section to demo_configs.rst - Remove standalone configuration.rst (duplicated content) - Update index.rst to remove configuration from API Reference

…o/experanto into claude/add-docstrings-KhA9Q

- Remove query language from Interpolator base class - Add TimeIntervalInterpolator class docstring with full detail - Minimize all interpolate method docstrings (detail lives in classes) - Add TimeIntervalInterpolator to Interpolator See Also section

…o/experanto into claude/add-docstrings-KhA9Q

schewskone

Cool PR! Thanks @oliveira-caio
Not sure about the TeX formatting inside the code itself.
Can it be used for automated docstrings in readthedocs where it is formatted properly?

schewskone · 2026-01-30T13:49:41Z

docs/source/concepts/demo_configs.rst

+``global_sampling_rate``
+   Override sampling rate for all modalities. Set to ``null`` to use per-modality rates.


Why null and not None in these examples?

schewskone · 2026-01-30T13:53:56Z

docs/source/concepts/demo_configs.rst

+   and ``"standardize"`` (z-score normalization).
+
+``interpolation``
+   Interpolation settings including ``interpolation_mode`` (``"linear"`` or


Maybe mention that this is only for Sequence interpolators

schewskone · 2026-01-30T14:13:51Z

experanto/interpolators.py

+
+    .. math::
+
+        y(t) = y_0 \\cdot \\frac{t_1 - t}{t_1 - t_0} + y_1 \\cdot \\frac{t - t_0}{t_1 - t_0},


Suggested change

y(t) = y_0 \\cdot \\frac{t_1 - t}{t_1 - t_0} + y_1 \\cdot \\frac{t - t_0}{t_1 - t_0},

y = y0 * (t1 - t) / (t1 - t0) + y1 * (t - t0) / (t1 - t0)

Markdown does not work here right or is this useful for readthedocs?

At least locally it works for me

I guess because the mathjax extension was added to readthedocs?! see https://github.com/sensorium-competition/experanto/pull/96/changes#diff-008dcb3426febd767787b1521f1fe33086313b927ea37eaab86df5fa88a51698R27

schewskone · 2026-01-30T14:14:35Z

experanto/interpolators.py

+
+        y(t) = y_0 \\cdot \\frac{t_1 - t}{t_1 - t_0} + y_1 \\cdot \\frac{t - t_0}{t_1 - t_0},
+
+    where :math:`t_0` and :math:`t_1` are the surrounding sample times.


Suggested change

where :math:`t_0` and :math:`t_1` are the surrounding sample times.

where t_0 and t_1 are the surrounding sample times.

reneburghardt · 2026-02-05T14:42:11Z

docs/source/concepts/demo_configs.rst

+
+``transforms``
+   Dictionary of transforms to apply. Supports ``"normalize"`` (0-1 scaling)
+   and ``"standardize"`` (z-score normalization).


Actually supports also custom transforms, defined as dicts containing key _target_ whose value contains a class + optional arguments as further key-value pairs.
E.g., something like this

"SelectOdorProperties": { "_target_": "odor_model.dataset_transforms.SelectOdorTrialPropertiesAsModalitiesTransform", "properties": ["graph"], }

reneburghardt · 2026-02-05T14:43:16Z

docs/source/concepts/demo_configs.rst

+   Sampling rate in Hz for this modality.
+
+``chunk_size``
+   Number of samples per chunk.


Not sure myself, but maybe "data points" or "time steps" is better than "samples" here.

reneburghardt · 2026-02-05T14:53:43Z

experanto/interpolators.py

+
+    Interpolators load data from a modality folder and map time points to
+    data values. Each modality (e.g., screen, responses, eye_tracker,
+    treadmill) has a specialized interpolator subclass.


I think I still not agree that each modality has a specialized interpolator subclass.
I think we have interpolator subclasses for different temporal representations, e.g. SequenceInterpolator for continuous signals (ScreenInterpolator is basically a special instance of that as images and videos need special handling for efficiency), TimeIntervalInterpolator for bounded intervals and later SpikesInterpolator and EventInterpolator for timestamps.

claude and others added 30 commits January 25, 2026 12:35

docs: configure Sphinx for NumPy-style docstrings and API docs

55a7561

Add extensions for autodoc, napoleon, mathjax, intersphinx, and viewcode. Configure napoleon for NumPy-style docstrings with math rendering support and cross-references to Python, NumPy, SciPy, and PyTorch documentation.

docs: add autodoc mock imports and API reference page

e76a773

- Add autodoc_mock_imports for heavy dependencies (torch, numpy, etc.) - Create api.rst with single-page API reference for all modules - Update index.rst to include API Reference section

docs: add comprehensive codebase analysis document

9851e7c

Document package architecture, class relationships, data flow, potential bugs, and docstring requirements with priority levels.

docs: remove codebase analysis file (saved locally)

4ecd8fc

chore: ignore local TODO_AND_ISSUES.md

e2d9715

fix: remove duplicate device_names from Attributes section

38f68b8

docs: configure Sphinx for NumPy-style docstrings and API docs

8c7c3c1

Add extensions for autodoc, napoleon, mathjax, intersphinx, and viewcode. Configure napoleon for NumPy-style docstrings with math rendering support and cross-references to Python, NumPy, SciPy, and PyTorch documentation.

docs: add autodoc mock imports and API reference page

da06202

- Add autodoc_mock_imports for heavy dependencies (torch, numpy, etc.) - Create api.rst with single-page API reference for all modules - Update index.rst to include API Reference section

docs: add comprehensive codebase analysis document

028147e

Document package architecture, class relationships, data flow, potential bugs, and docstring requirements with priority levels.

docs: remove codebase analysis file (saved locally)

852f600

chore: ignore local TODO_AND_ISSUES.md

ccc361b

fix: remove duplicate device_names from Attributes section

5a278fd

minor changes in docstrings.

45e19ef

Merge branch 'claude/add-docstrings-KhA9Q' of github.com:oliveira-cai…

4a24327

…o/experanto into claude/add-docstrings-KhA9Q

minor changes in docstrings.

acbcb20

docs: convert remaining docstrings to NumPy style

3654d80

- datasets.py: get_data_key_from_root_folder - interpolators.py: rescale_frame - utils.py: SessionBatchSampler.__init__, SessionSpecificSampler.__init__

docs: restructure API with autosummary for separate pages

d44017d

- Add sphinx.ext.autosummary extension - Create custom class template for detailed docs - Reorganize api.rst with autosummary tables - Each class/function now gets its own page

docs: move configuration to dedicated page with default.yaml content

0491519

- Create configuration.rst with full default.yaml embedded - Add documentation for all configuration options - Update index.rst to include configuration page

docs: rename API page to avoid duplicate sidebar entry

79bed6c

docs: rename toctree caption to Reference to avoid confusion

9019d34

minor spelling changes.

d34fbee

docs: rewrite README with professional structure

97d194b

- Add features section highlighting key capabilities - Include quick start examples for Experiment and DataLoader - Add configuration snippet and documentation links - Add contributing, license, and citation sections

modified readme.

26aa980

removed local files from gitignore.

8d093e7

added docs/source/generated back to gitignore.

6dd5782

oliveira-caio requested review from pollytur, reneburghardt and schewskone January 25, 2026 18:28

oliveira-caio added the documentation Improvements or additions to documentation label Jan 25, 2026

ran black.

0c2576e

reneburghardt requested a review from Copilot January 28, 2026 15:08

Copilot started reviewing on behalf of reneburghardt January 28, 2026 15:09 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

experanto/experiment.py Outdated Show resolved Hide resolved

experanto/datasets.py Outdated Show resolved Hide resolved

reneburghardt requested changes Jan 28, 2026

View reviewed changes

experanto/interpolators.py Show resolved Hide resolved

docs/source/api.rst Show resolved Hide resolved

experanto/datasets.py Outdated Show resolved Hide resolved

experanto/datasets.py Outdated Show resolved Hide resolved

experanto/interpolators.py Outdated Show resolved Hide resolved

oliveira-caio and others added 13 commits January 29, 2026 14:48

fixed minor issues with the pyproject.toml

2ef1499

minor fixes in the docstrings and readme.

9c86b1e

docs: add NumPy-style docstring to nan_filter and clean up comments

313bd9b

docs: add inline comments back to nan_filter implementation

3a00795

docs: merge configuration reference into tutorials page

427654c

- Add configuration options section to demo_configs.rst - Remove standalone configuration.rst (duplicated content) - Update index.rst to remove configuration from API Reference

docs: replace dataloader options with link to PyTorch docs

25b60fe

minor changes in the demo_configs.rst

3975057

Merge branch 'claude/add-docstrings-KhA9Q' of github.com:oliveira-cai…

138f058

…o/experanto into claude/add-docstrings-KhA9Q

docs: add Sphinx cross-references to tutorial pages

0be8971

Merge branch 'claude/add-docstrings-KhA9Q' of github.com:oliveira-cai…

326b050

…o/experanto into claude/add-docstrings-KhA9Q

minor fix to the pip install.

ee749f8

ran black.

8242d84

oliveira-caio requested a review from reneburghardt January 29, 2026 16:03

schewskone reviewed Jan 30, 2026

View reviewed changes

reneburghardt reviewed Feb 5, 2026

View reviewed changes

		``global_sampling_rate``
		Override sampling rate for all modalities. Set to ``null`` to use per-modality rates.


		.. math::

		y(t) = y_0 \\cdot \\frac{t_1 - t}{t_1 - t_0} + y_1 \\cdot \\frac{t - t_0}{t_1 - t_0},

	y(t) = y_0 \\cdot \\frac{t_1 - t}{t_1 - t_0} + y_1 \\cdot \\frac{t - t_0}{t_1 - t_0},
	y = y0 * (t1 - t) / (t1 - t0) + y1 * (t - t0) / (t1 - t0)


		y(t) = y_0 \\cdot \\frac{t_1 - t}{t_1 - t_0} + y_1 \\cdot \\frac{t - t_0}{t_1 - t_0},

		where :math:`t_0` and :math:`t_1` are the surrounding sample times.

	where :math:`t_0` and :math:`t_1` are the surrounding sample times.
	where t_0 and t_1 are the surrounding sample times.

Conversation

oliveira-caio commented Jan 25, 2026

Summary

Changes

Docstrings

Documentation Structure

README

Uh oh!

gitnotebooks bot commented Jan 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

reneburghardt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

schewskone left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants