Lint rezconfig.py for common mistakes

[JeanChristopheMorinPerso]

A common mistake make by most people (including me) when editing the rezconfig.py is is to either forget to add documentation or to add a .. versionadded sphinx directive.

This PR adds a custom linter that can detect both of the problems. It can also detect if a setting is added outside a section.

To achieve that, I refactored the code to extract the docs that was in the sphinx extension into its own module.

The linting happens inside the tests. That's the "cleanest" option I found that allows to catch these problems locally and in CI.

Note that this PR is mostly AI generated using Amp: https://ampcode.com/threads/T-019fbef7-632f-767e-ad1c-68582e67859f

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.38%. Comparing base (a4160c2) to head (d1244c0).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rez/utils/docs.py	95.16%	1 Missing and 2 partials ⚠️
src/rez/cli/selftest.py	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2176      +/-   ##
==========================================
+ Coverage   61.29%   61.38%   +0.09%     
==========================================
  Files         164      165       +1     
  Lines       20568    20633      +65     
  Branches     3575     3594      +19     
==========================================
+ Hits        12607    12666      +59     
- Misses       7089     7094       +5     
- Partials      872      873       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR introduces a reusable parser for “documented settings” inside rezconfig.py and uses it in unit tests to lint for common rezconfig documentation mistakes (missing section placement, missing docs, missing .. versionadded:: for new settings). It also updates the Sphinx extension to reuse the same parsing logic and adjusts CI/selftest so the “new settings” check can compare against the appropriate Git baseline.

Changes:

• Added rez.utils.docs.parse_documented_settings() to extract documented rezconfig settings (names, values, comment blocks, and section metadata).
• Added selftests that enforce rezconfig documentation conventions, including a Git-aware “new settings must include .. versionadded::” rule.
• Updated the Sphinx extension and CI workflow to rely on the shared parsing code and provide sufficient Git history/baseline information.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/rez/utils/docs.py	New shared parser for documented rezconfig settings used by both docs generation and tests.
src/rez/tests/test_utils_docs.py	Unit tests validating the documented-settings parser and the “versionadded must be in the immediately preceding comment block” behavior.
src/rez/tests/test_rezconfig.py	New lint-style tests enforcing rezconfig documentation/section rules and Git-baseline comparison for new settings.
src/rez/cli/selftest.py	Adds --rezconfig-baseline option to pass a baseline revision into selftests via env var.
docs/rez_sphinxext.py	Refactors rezconfig-to-RST generation to use the new shared parser.
.github/workflows/tests.yaml	Ensures full Git history is available and passes an appropriate baseline SHA to rez-selftest in CI.

---

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