enforce 'rstcheck' checks

[jameslamb]

Contributes to rapidsai/build-planning#262

Proposes introducing rstcheck (rstcheck/rstcheck), a linter for ReStructuredText.

In my experience, it runs pretty quickly and catches things that sphinx-build -W does not, like:

• invalid syntax in .. code-block:: blocks
• duplicated references (which can lead to unexpected behavior when sharing URLs with anchors)

Notes for Reviewers

Planning to try this across all of RAPIDS, but starting here partially because @jcrist and I talked about .rst linting at SciPy 😊

[jameslamb]

There's a section title also called Examples in this page, which made the reference #examples ambiguous.

Changing this to an anonymous URL resolves that.

[csadorf]

Thanks!

[jameslamb]

Any of these code blocks with cell magic like %load_ext are reported as invalid syntax and Python code that follows them may not render correctly.

Using ipython fixes that. And works because cuML already uses a Sphinx extension to support that highlighting:

https://github.com/rapidsai/cuml/blob/0f4af33b1b003c6a57de4557661ea41f24857bbe/docs/source/conf.py#L52

[jameslamb]

There are 2 references in this file both name "Introductory Notebook". Making these anonymous links resolves that.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Improved rendering of documentation links and cross-references.
  • Updated Jupyter and IPython examples to use appropriate syntax highlighting.
• Chores
  • Updated pre-commit tooling.
  • Added automated reStructuredText documentation checks with project-specific validation settings.

Walkthrough

The pull request adds rstcheck to pre-commit validation, configures its accepted directives and ignored messages, and updates documentation code-block and hyperlink markup.

Changes

Documentation tooling and markup

Layer / File(s)	Summary
Configure rstcheck validation .pre-commit-config.yaml, pyproject.toml	Adds the rstcheck hook, updates pre-commit-hooks, and configures rstcheck handling for project documentation.
Update documentation markup docs/source/cuml-accel/**/*.rst, docs/source/cuml_intro.rst	Marks Jupyter examples as ipython blocks and corrects selected reStructuredText link markup.

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

Suggested labels: doc

Suggested reviewers: bdice, msarahan, betatim

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the main change: enforcing rstcheck checks.
Description check	✅ Passed	The description directly explains the new rstcheck linter and why it was added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@pyproject.toml`:
- Around line 42-45: Restrict the rstcheck ignore pattern in ignore_messages to
the documented stable-anchor names or a narrowly defined anchor allowlist,
rather than matching every “Hyperlink target .* is not referenced” warning.
Preserve suppression for known intentional anchors while allowing typo and
dead-anchor warnings to surface.

🪄 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: 0c34c479-06c0-4c8a-b109-38fe1d56072c

📥 Commits

Reviewing files that changed from the base of the PR and between 0f4af33 and 6f1bfb9.

📒 Files selected for processing (8)

• .pre-commit-config.yaml
• docs/source/cuml-accel/examples/index.rst
• docs/source/cuml-accel/faq.rst
• docs/source/cuml-accel/index.rst
• docs/source/cuml-accel/logging-and-profiling.rst
• docs/source/cuml-accel/usage.rst
• docs/source/cuml_intro.rst
• pyproject.toml

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Scope the rstcheck ignore to known anchors. Hyperlink target .* is not referenced suppresses every unreferenced-target warning, so typos and dead anchors will be missed; restrict this to explicit anchors or a narrower allowlist. pyproject.toml:42-45

🤖 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 `@pyproject.toml` around lines 42 - 45, Restrict the rstcheck ignore pattern in
ignore_messages to the documented stable-anchor names or a narrowly defined
anchor allowlist, rather than matching every “Hyperlink target .* is not
referenced” warning. Preserve suppression for known intentional anchors while
allowing typo and dead-anchor warnings to surface.

[jameslamb]

Example of this:

https://github.com/rapidsai/cuml/blob/0f4af33b1b003c6a57de4557661ea41f24857bbe/docs/source/cuml_intro.rst#L19

Without this configuration, rstcheck reports:

docs/source/cuml_intro.rst:19: (INFO/1) Hyperlink target "where-possible-match-the-scikit-learn-api" is not referenced.

But we want to keep that, because it creates this anchor: https://docs.rapids.ai/api/cuml/nightly/cuml_intro/#where-possible-match-the-scikit-learn-api