swev-id: sphinx-doc__sphinx-8638 Prevent spurious variable xrefs

[casey-brooks]

Summary

• add the python_docstring_variable_xrefs config flag so projects can disable auto cross-references for :var:/ :ivar:/ :cvar:
• make the Python docstring variable field emit literals when disabled while preserving type cross references
• cover the behavior with new docdomain tests and an integration fixture

Reproduction Steps

1. Clone https://github.com/13steinj/sphinx-issue-examples and checkout the referenced_variables branch.
2. Build the docs with the default configuration: sphinx-build -b html docs _build/html.
3. Open _build/html/index.html and inspect the Attributes section for Sample.foo.

Observed: the attribute name links to the unrelated foo() function. (Stack trace: not applicable; this is a behavioral regression.)

Testing

• source .venv/bin/activate && PYTHONPATH=/workspace/sphinx pytest tests/test_domain_py.py -q
• source .venv/bin/activate && flake8 sphinx/domains/python.py tests/test_domain_py.py

Resolves #66

[casey-brooks]

Test & Lint Summary

• source .venv/bin/activate && PYTHONPATH=/workspace/sphinx pytest tests/test_domain_py.py -q
  • 37 passed, 0 failed, 0 skipped
• source .venv/bin/activate && flake8 sphinx/domains/python.py tests/test_domain_py.py
  • no lint errors

[noa-lucent]

The implementation and tests look good, but the new configuration option needs to be documented so users can discover and understand it.

[casey-brooks]

Documentation update pushed:

• documented :confval:python_docstring_variable_xrefs in the configuration reference with usage example and behaviour notes
• added autodoc guidance about toggling docstring variable cross-references and recorded the change in CHANGES
• built the HTML docs locally to confirm a clean build

Doc Build

• source .venv/bin/activate && make -C doc html
  • build succeeded with no warnings after installing sphinxcontrib-websupport==1.2.4 and graphviz via nix

[noa-lucent]

Documentation looks great now. Thanks for the quick follow-up!