docs: enforce heading title case with Vale - #1668
Merged
Merged
Conversation
Heading capitalization has only been caught by human review. Add a Vale
prose-lint hook so it is checked mechanically.
The rule uses Chicago style, which keeps short prepositions and
conjunctions lowercase ('Where to Find Examples'), matching how these
docs already read. Fixes the 22 existing headings that did not comply;
all are case-only edits, so RST underline lengths and HTML anchors are
unchanged.
Note that Vale exceptions match whole words and a single match skips the
entire heading, so the exceptions list must stay narrow. This is
documented in the rule file and docs/cuopt/README.md.
Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
The exceptions list carried 19 speculative entries. Each one is a liability rather than dead weight: Vale skips an entire heading when an exception matches it, so an unnecessary term silently stops the rule from checking every heading that mentions it. A leave-one-out check showed only 7 of the 26 entries were load-bearing; drop the rest. Add ci/utils/check_vale_rule.sh to make that failure mode loud. It asserts the rule still flags known violations and still accepts correct headings, and runs as a pre-commit hook whenever ci/vale/ changes, so a weakened rule fails CI instead of passing quietly. Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
The fixtures were only ever input to the self-test; Vale needs a file to lint, so the test has to hand it a document. Build them in a temp dir from two lists at the top of the script rather than keeping three files under ci/vale/tests, which keeps the expected headings next to the assertions that use them. Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
Keep the surface minimal. The README now shows the one-line manual check to run after editing the exceptions list instead. Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
Collaborator
Author
|
/ok to test b6d932e |
ramakrishnap-nv
marked this pull request as ready for review
August 5, 2026 15:40
ramakrishnap-nv
marked this pull request as draft
August 5, 2026 15:41
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (5)
🚧 Files skipped from review as they are similar to previous changes (4)
📝 WalkthroughWalkthroughVale now checks cuOpt documentation headings with a custom Chicago title-case rule. The check runs through pre-commit and uses pinned Conda dependencies. Existing documentation headings were updated to satisfy the rule. ChangesDocumentation prose linting
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Comment |
CI Test Summary✅ All 31 test job(s) passed. |
ramakrishnap-nv
added
doc
Vale parses .rst by shelling out to docutils' rst2html. The checks environment does not otherwise pull in docutils, so the vale hook failed in CI with 'rst2html not found' while passing locally, where Sphinx (and a system python3-docutils) already provide the binary. Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>
Collaborator
Author
|
/ok to test 750b93c |
ramakrishnap-nv
marked this pull request as ready for review
August 5, 2026 19:35
tmckayus
approved these changes
Aug 5, 2026
Collaborator
Author
|
/merge |
rapids-bot Bot
pushed a commit
that referenced
this pull request
Aug 6, 2026
## Summary Fixes three heading case errors flagged by the Vale prose linter (added in #1668) in docs that were merged in #1653 before Vale was introduced. - `python-async-client-api.rst`: `See also` → `See Also` - `index.rst`: `When to choose which path` → `When to Choose Which Path` - `python-async-client.rst`: `Next steps` → `Next Steps` These errors are currently blocking check-style on every open PR. ## Testing Pre-commit passes on all three files. ## Docs Heading text only — no content change. Authors: - Ramakrishna Prabhu (https://github.com/ramakrishnap-nv) Approvers: - Ishika Roy (https://github.com/Iroy30) URL: #1682
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
3 participants
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.
Heading capitalization has so far only been caught in human review. This adds a Vale prose-lint hook so it is checked mechanically, and fixes the existing headings that do not comply.
The rule uses Chicago style, which keeps short prepositions and conjunctions lowercase (
Where to Find Examples,Working with Incumbent Solutions) — matching how these docs already read. It also catches the opposite error: existing headings such asLP Example With Datathat over-capitalize.All 22 heading fixes are case-only, so RST underline lengths and HTML anchors are unchanged.
Verification
vale docs/cuopt/source— 0 errors in 66 filespre-commit run --all-files— all hooks pass./build.sh docs— exit 0, html + linkcheck, zero Sphinx warnings (confirms noautosectionlabelcross-reference broke)Reviewer note
Vale's
exceptionsmatch whole words, and a single match makes Vale skip the entire heading. A too-broad entry therefore silently disables the check for every heading that mentions it. The list must stay narrow, andvaleshould be re-run after editing it — documented in bothci/vale/styles/cuOpt/Headings.ymlanddocs/cuopt/README.md.Follow-up
A
substitutionrule for MILP → MIP is the natural next step, but it cannot be added until #1653 merges —mainstill has 21 MILP occurrences that #1653 removes, and CI runspre-commiton all files.