Enable numpydoc validation by pathak-satyam · Pull Request #23439 · rapidsai/cudf

pathak-satyam · 2026-07-27T04:37:45Z

Description

closes #11253

Checklist

I am familiar with the Contributing Guidelines.
New or existing tests cover these changes.
The documentation is up to date with these changes.

copy-pr-bot · 2026-07-27T04:37:48Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

coderabbitai · 2026-07-27T04:42:46Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6e0e57da-5e90-4f09-ab96-0e30a0befcb6

📥 Commits

Reviewing files that changed from the base of the PR and between 9b29a3f and 5e97cc3.

📒 Files selected for processing (2)

.pre-commit-config.yaml
python/cudf/pyproject.toml

💤 Files with no reviewable changes (2)

.pre-commit-config.yaml
python/cudf/pyproject.toml

📝 Walkthrough

Summary by CodeRabbit

Documentation
- Expanded and standardized documentation for configuration options and option-management utilities.
- Added clearer parameter and return-value details for retrieving options.
- Improved guidance for using temporary option contexts.
- Added a module-level description and clarified function descriptions.
Chores
- Simplified internal documentation-validation configuration comments without changing validation behavior.

Walkthrough

Retains Numpydoc validation settings while removing explanatory configuration comments. Expands and normalizes documentation for the cuDF options module and selected public APIs without changing behavior.

Changes

Numpydoc validation rollout

Layer / File(s)	Summary
Validation integration `.pre-commit-config.yaml`, `python/cudf/pyproject.toml`	Retains the existing Numpydoc file allowlist, checks, and exclusions while removing explanatory comments.
Options API docstring cleanup `python/cudf/cudf/options.py`	Adds module and dataclass documentation, structures `get_option` documentation, and clarifies `describe_option` and `option_context` docstrings.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: improvement

Suggested reviewers: brandon-b-miller, gforsyth, mroeschke

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: enabling numpydoc validation.
Description check	✅ Passed	The description is relevant to the docstring validation changes and related documentation updates.
Linked Issues check	✅ Passed	The PR enables numpydoc validation and fixes docstrings to satisfy the linked issue's goal of semantic docstring checking.
Out of Scope Changes check	✅ Passed	The changes stay within validation config and docstring cleanup, with no clear unrelated code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Fix failing CI checks

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

🤖 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 `@PROGRESS.md`:
- Line 10: Refresh the progress journal metadata to reflect the current pull
request state, including that the pull request has been opened if applicable,
the complete changed-file count including python/cudf/cudf/options.py and the
Phase III journal update, and an accurate “What’s Next” section. If preserving
the existing values, clearly label the status, counts, and next steps as a
historical snapshot.

In `@python/cudf/cudf/options.py`:
- Around line 355-359: The option_context docstring uses inconsistent invocation
syntax. Update the preceding usage description in option_context to show the
flat alternating name/value form, matching the *args description and example,
and remove the outdated tuple-list form that implies an invalid argument count.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8bf74f25-0558-4c1b-9c0f-2a27da6d6b88

📥 Commits

Reviewing files that changed from the base of the PR and between 3a3a522 and 5484e50.

📒 Files selected for processing (4)

.pre-commit-config.yaml
PROGRESS.md
python/cudf/cudf/options.py
python/cudf/pyproject.toml

…ai#11253) Wire up the numpydoc-validation pre-commit hook (numpy/numpydoc v1.9.0) for cuDF's public Python API. The package is not yet docstring-clean (~4,143 pre-existing violations across 154 of 155 files), so enabling a repo-wide gate would break CI immediately. Instead, enforce validation on an explicit allowlist of files that already pass, to be grown one PR at a time so CI stays green throughout the rollout. - .pre-commit-config.yaml: add the hook, scoped to a 10-file allowlist. - python/cudf/pyproject.toml: add [tool.numpydoc_validation]; enable all semantic checks, deselect optional/stylistic ones, and exclude protocol dunders and module-private helpers (validation targets the public API). - python/cudf/cudf/options.py: fix genuine docstring bugs so the module passes validation. get_option documented a nonexistent `key` parameter instead of `name` and had no return description; describe_option's summary used "Prints" instead of the infinitive "Print"; option_context did not document *args and showed an invalid invocation form. Also document the module and Option dataclass. Docstring-only; no behavior change.

pathak-satyam · 2026-07-27T05:01:07Z

Thanks for the review! I've pushed revisions addressing the feedback:

option_context docstring: corrected to the flat alternating invocation form option_context(pat1, val1, pat2, val2, ...), matching the *args description and the example.
Removed PROGRESS.md: it was an unrelated personal note and didn't belong in this PR. The branch now contains only the pre-commit hook, the [tool.numpydoc_validation] config, and the options.py docstring fixes.

Quick summary for reviewers: this enables numpydoc validation on an explicit allowlist of 10 already-compliant files (rather than the whole package, which still has ~4,143 pre-existing violations), so CI stays green while the allowlist grows one PR at a time.

This is a non-breaking improvement / docs change — could a maintainer add the improvement and non-breaking labels when convenient? That's the one remaining required check I can't clear as an external contributor.

mroeschke

Thanks for the start!

mroeschke · 2026-07-27T15:20:35Z

+# See https://numpydoc.readthedocs.io/en/latest/validation.html for the full
+# list of check codes. We enable all semantic checks and disable only the
+# optional/stylistic ones below. Remaining violations are cleaned up
+# incrementally, a few check codes at a time (see cuDF issue #11253).


Suggested change

# See https://numpydoc.readthedocs.io/en/latest/validation.html for the full

# list of check codes. We enable all semantic checks and disable only the

# optional/stylistic ones below. Remaining violations are cleaned up

# incrementally, a few check codes at a time (see cuDF issue #11253).

mroeschke · 2026-07-27T15:21:13Z

+        # Validation is configured under [tool.numpydoc_validation] in
+        # python/cudf/pyproject.toml. The whole cudf package is not yet
+        # docstring-clean, so we enforce validation on an explicit allowlist of
+        # already-compliant files and grow it incrementally, one PR at a time,
+        # keeping CI green throughout (see cuDF issue #11253).


Suggested change

# Validation is configured under [tool.numpydoc_validation] in

# python/cudf/pyproject.toml. The whole cudf package is not yet

# docstring-clean, so we enforce validation on an explicit allowlist of

# already-compliant files and grow it incrementally, one PR at a time,

# keeping CI green throughout (see cuDF issue #11253).

mroeschke · 2026-07-27T15:24:48Z

+        # docstring-clean, so we enforce validation on an explicit allowlist of
+        # already-compliant files and grow it incrementally, one PR at a time,
+        # keeping CI green throughout (see cuDF issue #11253).
+        files: |


Can we specify files to exclude instead?

mroeschke · 2026-07-27T15:24:59Z

+    "SA04",  # description in see also not required
+    "SS06",  # allow summaries that span more than a single line
+]
+# Skip objects that do not benefit from full docstring validation.


Suggested change

# Skip objects that do not benefit from full docstring validation.

pathak-satyam · 2026-07-30T01:15:48Z

Thanks! I looked into exclude_files from that page — two findings:

It isn't available in the pinned numpydoc v1.9.0. That release's hook only reads checks, exclude, and overrides; exclude_files was added later, so using it would need a rev bump.
More importantly, exclusion is the larger list here. Only 10 of 155 non-test files under python/cudf/cudf/ currently pass, so an exclude list would need ~145 entries (plus the tests/ tree) vs 10 for the allowlist — and the passing files are scattered (options.py, _typing.py, core/_compat.py, …), so they don't collapse into directory patterns.

So the files: allowlist is the smaller, more readable list today and grows one PR at a time as modules are cleaned. Once most of the package passes, I'm happy to flip it — bump numpydoc and switch to exclude_files so new files are validated by default. Keep the allowlist for now, or go the bump + exclude_files route?

mroeschke · 2026-07-30T15:56:30Z

I suggest to bump the numpydoc version to specify exclusions instead, as it will be easier to know what needs correcting in the future.

pathak-satyam requested review from a team as code owners July 27, 2026 04:37

pathak-satyam requested review from brandon-b-miller, gforsyth and mroeschke July 27, 2026 04:37

github-actions Bot assigned pathak-satyam Jul 27, 2026

github-actions Bot added the Python Affects Python cuDF API. label Jul 27, 2026

github-project-automation Bot added this to cuDF Python Jul 27, 2026

GPUtester moved this to In Progress in cuDF Python Jul 27, 2026

coderabbitai Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread PROGRESS.md Outdated

Comment thread python/cudf/cudf/options.py

pathak-satyam force-pushed the enable-numpydoc-validation branch from e1fbb36 to 9b29a3f Compare July 27, 2026 04:56

mroeschke requested changes Jul 27, 2026

View reviewed changes

Remove verbose numpydoc config comments per review

5e97cc3

Uh oh!

Conversation

pathak-satyam commented Jul 27, 2026 • edited by mroeschke Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

copy-pr-bot Bot commented Jul 27, 2026

Uh oh!

coderabbitai Bot commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pathak-satyam commented Jul 27, 2026

Uh oh!

mroeschke left a comment

Choose a reason for hiding this comment

Uh oh!

mroeschke Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

mroeschke Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

mroeschke Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

mroeschke Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

pathak-satyam commented Jul 30, 2026

Uh oh!

mroeschke commented Jul 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pathak-satyam commented Jul 27, 2026 •

edited by mroeschke

Loading

coderabbitai Bot commented Jul 27, 2026 •

edited

Loading