Fix sphinx warnings

[JeanChristopheMorinPerso]

Fix Sphinx warnings caused by duplicate symbols by introducing two new Sphinx domains: rex and pkgdef.

This makes it possible to reference package attributes in the docs using :pkgdef:attr for example, and stuff in commands using :rex:attr.

This removes any duplicates in symbols. These new domains won't affect users reading our docs in any way, but it will have an impact on any user that are cross-linking our docs using intersphinx (https://docs.readthedocs.com/platform/latest/guides/intersphinx.html). These users will have to update references to :data:version, etc to use our domains instead.

I also fixed some more warnings that were not related to the duplicate symbols, and modified the CLI docs auto-generation code to improve the readability of the docs a little bit (please look at https://rez--2062.org.readthedocs.build/en/2062/commands_index.html?readthedocs-diff=true to visualize the diff).

AI disclosure:

The custom domains code was written using Amp. Here are the threads:

• https://ampcode.com/threads/T-019b854a-b579-770f-bbd2-6f3c7283d9e1
• https://ampcode.com/threads/T-019b855b-4386-74db-a9c1-163b3a62f297
• https://ampcode.com/threads/T-019b8568-e761-736f-b079-246e9724cf42
• https://ampcode.com/threads/T-019b857b-ab87-73df-acf4-1faae6673a88

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.04%. Comparing base (d9e2211) to head (2dc112d).
⚠️ Report is 48 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2062      +/-   ##
==========================================
- Coverage   60.05%   60.04%   -0.01%     
==========================================
  Files         164      164              
  Lines       20559    20559              
  Branches     3571     3571              
==========================================
- Hits        12346    12344       -2     
- Misses       7345     7346       +1     
- Partials      868      869       +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 addresses Sphinx build warnings caused by duplicate symbols by introducing two new Sphinx domains (rex and pkgdef) and updating documentation cross-references to use them. It also includes several smaller docstring/help-text adjustments and changes to the CLI docs auto-generation for readability.

Changes:

• Add custom Sphinx domains (rex, pkgdef) to disambiguate symbols and update docs to reference them (eg :pkgdef:attr:, :rex:func:).
• Adjust multiple docs/docstrings to reduce Sphinx warnings and improve cross-linking clarity.
• Update CLI docs generation ordering/formatting and default/choices presentation.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
docs/rez_sphinxext.py	Adds rex/pkgdef Sphinx domains and modifies CLI RST auto-generation.
src/rez/rezconfig.py	Updates config documentation cross-references to use new domains.
src/rez/package_test.py	Updates docstring cross-references to pkgdef domain.
src/rez/package_copy.py	Updates docstring cross-reference for relocatable.
src/rez/package_cache.py	Docstring tweaks (logging.Logger typing, :meth: role).
src/rez/cli/selftest.py	Help text typo/format fix for pytest flag reference.
src/rez/cli/search.py	Help text example formatting tweak.
src/rez/cli/env.py	Help text formatting tweak for -c flag reference.
src/rez/build_process.py	Docstring deprecation wording/format adjustment.
docs/source/variants.rst	Switch attribute references to pkgdef domain.
docs/source/suites.rst	Switch attribute references to pkgdef domain.
docs/source/package_orderers.rst	Switch attribute references to pkgdef domain.
docs/source/package_definition.rst	Large sweep updating roles/directives to pkgdef and rex domains.
docs/source/package_commands.rst	Updates directives/roles to rex/pkgdef and refines wording.
docs/source/managing_packages.rst	Updates relocatable reference to pkgdef domain.
docs/source/ephemerals.rst	Updates commands/rex object references to new domains.
docs/source/environment.rst	Updates commands and build-requires attribute references to pkgdef.
docs/source/context.rst	Updates commands references to pkgdef domain.
docs/source/caching.rst	Updates cachable references to pkgdef domain.
docs/source/building_packages.rst	Updates build-related attribute references to pkgdef/rex.
docs/source/basic_concepts.rst	Updates introductory references to pkgdef domain.

---

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

[maxnbk]

Huh.

[maxnbk]

LGTM other than the Copilot regexes, unsure about those comments