sphinxdocs: allow unqualified arg/attr name for xref (bazel-contrib#2896)

rickeylev · web-flow · commit dcf0511675a4 · 2025-05-17T23:57:31.000Z
It's common to simply refer to an arg or attribute by its sole name,
especially for
ones that are unique.

This fixes about ~20 broken xrefs in our docs. Also add test for this
behavior.
diff --git a/sphinxdocs/src/sphinx_bzl/bzl.py b/sphinxdocs/src/sphinx_bzl/bzl.py
@@ -390,8 +390,12 @@ def _make_xrefs_for_arg_attr(
                     descr=index_description,
                 ),
             ),
-            # This allows referencing an arg as e.g `funcname.argname`
-            alt_names=[anchor_id],
+            alt_names=[
+                # This allows referencing an arg as e.g `funcname.argname`
+                anchor_id,
+                # This allows referencing an arg as simply `argname`
+                arg_name
+            ],
         )
 
         # Two changes to how arg xrefs are created:
diff --git a/sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py b/sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py
@@ -64,6 +64,8 @@ def _doc_element(self, doc):
         ("full_repo_aspect", "@testrepo//lang:aspect.bzl%myaspect", "aspect.html#myaspect"),
         ("full_repo_target", "@testrepo//lang:relativetarget", "target.html#relativetarget"),
         ("tag_class_attr_using_attr_role", "myext.mytag.ta1", "module_extension.html#myext.mytag.ta1"),
+        ("tag_class_attr_using_attr_role_just_attr_name", "ta1", "module_extension.html#myext.mytag.ta1"),
+
         # fmt: on
     )
     def test_xrefs(self, text, href):
diff --git a/sphinxdocs/tests/sphinx_stardoc/xrefs.md b/sphinxdocs/tests/sphinx_stardoc/xrefs.md
@@ -45,3 +45,4 @@ Various tests of cross referencing support
 ## Tag class refs
 
 * tag class attribute using attr role: {attr}`myext.mytag.ta1`
+* tag class attribute, just attr name, attr role: {attr}`ta1`

Original file line number	Diff line number	Diff line change
`@@ -64,6 +64,8 @@ def _doc_element(self, doc):`
`64`	`64`	`("full_repo_aspect", "@testrepo//lang:aspect.bzl%myaspect", "aspect.html#myaspect"),`
`65`	`65`	`("full_repo_target", "@testrepo//lang:relativetarget", "target.html#relativetarget"),`
`66`	`66`	`("tag_class_attr_using_attr_role", "myext.mytag.ta1", "module_extension.html#myext.mytag.ta1"),`
	`67`	`+ ("tag_class_attr_using_attr_role_just_attr_name", "ta1", "module_extension.html#myext.mytag.ta1"),`
	`68`	`+`
`67`	`69`	`# fmt: on`
`68`	`70`	`)`
`69`	`71`	`def test_xrefs(self, text, href):`
Original file line number	Diff line number	Diff line change
`@@ -45,3 +45,4 @@ Various tests of cross referencing support`
`45`	`45`	`## Tag class refs`
`46`	`46`
`47`	`47`	* tag class attribute using attr role: {attr}`myext.mytag.ta1`
	`48`	+* tag class attribute, just attr name, attr role: {attr}`ta1`