sphinxdocs: allow files to be xref

rickeylev · rickeylev · commit 88cee43e47a2 · 2025-05-17T16:43:00.000-07:00
diff --git a/sphinxdocs/src/sphinx_bzl/bzl.py b/sphinxdocs/src/sphinx_bzl/bzl.py
@@ -498,7 +498,40 @@ def run(self) -> list[docutils_nodes.Node]:
         self.env.ref_context["bzl:file"] = file_label
         self.env.ref_context["bzl:object_id_stack"] = []
         self.env.ref_context["bzl:doc_id_stack"] = []
-        return []
+
+        _, _, basename = file_label.partition(":")
+        index_description = f"File {label}"
+        absolute_label = repo + label
+        self.env.get_domain('bzl').add_object(
+                _ObjectEntry(
+                        full_id = absolute_label,
+                        display_name = absolute_label,
+                        object_type = 'obj',
+                        search_priority = 1,
+                        index_entry=domains.IndexEntry(
+                            name=basename,
+                            subtype=_INDEX_SUBTYPE_NORMAL,
+                            docname=self.env.docname,
+                            anchor="",
+                            extra="",
+                            qualifier="",
+                            descr=index_description,
+                        )
+
+                ),
+                alt_names = [
+                    # Allow xref //foo:bar.bzl
+                    file_label,
+                    # Allow xref bar.bzl
+                    basename,
+                ]
+        )
+        index_node = addnodes.index(
+            entries=[
+                _index_node_tuple("single", f"File; {label}", ""),
+            ]
+        )
+        return [index_node]
 
 
 class _BzlAttrInfo(sphinx_docutils.SphinxDirective):
diff --git a/sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py b/sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py
@@ -64,6 +64,9 @@ 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"),
+        ("file_without_repo", "//lang:rule.bzl", "rule.html"),
+        ("file_with_repo", "@testrepo//lang:rule.bzl", "rule.html"),
         # 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,9 @@ 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`
+
+## File refs
+
+* without repo {obj}`//lang:rule.bzl`
+* with repo {obj}`@testrepo//lang:rule.bzl`
