From 88cee43e47a2eae2bd77fa777484657fe44c7edd Mon Sep 17 00:00:00 2001
From: Richard Levasseur <rlevasseur@google.com>
Date: Sat, 17 May 2025 16:41:38 -0700
Subject: [PATCH 1/2] sphinxdocs: allow files to be xref

---
 sphinxdocs/src/sphinx_bzl/bzl.py              | 35 ++++++++++++++++++-
 .../sphinx_stardoc/sphinx_output_test.py      |  3 ++
 sphinxdocs/tests/sphinx_stardoc/xrefs.md      |  6 ++++
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/sphinxdocs/src/sphinx_bzl/bzl.py b/sphinxdocs/src/sphinx_bzl/bzl.py
index dc922056a6..bcf9ffd678 100644
--- 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
index 565c5ef68e..aa21369b40 100644
--- 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
index 8ff3e75d43..a32bb10339 100644
--- 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`

From 2600493bb07d56820b4f444a987b52b278cf336d Mon Sep 17 00:00:00 2001
From: Richard Levasseur <rlevasseur@google.com>
Date: Sat, 17 May 2025 17:03:00 -0700
Subject: [PATCH 2/2] py format

---
 sphinxdocs/src/sphinx_bzl/bzl.py | 45 ++++++++++++++++----------------
 1 file changed, 22 insertions(+), 23 deletions(-)

diff --git a/sphinxdocs/src/sphinx_bzl/bzl.py b/sphinxdocs/src/sphinx_bzl/bzl.py
index bcf9ffd678..bcbf222feb 100644
--- a/sphinxdocs/src/sphinx_bzl/bzl.py
+++ b/sphinxdocs/src/sphinx_bzl/bzl.py
@@ -502,29 +502,28 @@ def run(self) -> list[docutils_nodes.Node]:
         _, _, 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,
-                        )
-
+        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,
-                ]
+            ),
+            alt_names=[
+                # Allow xref //foo:bar.bzl
+                file_label,
+                # Allow xref bar.bzl
+                basename,
+            ],
         )
         index_node = addnodes.index(
             entries=[
@@ -1522,7 +1521,7 @@ class _BzlDomain(domains.Domain):
         "type": domains.ObjType("type", "type", "obj"),
         "typedef": domains.ObjType("typedef", "typedef", "type", "obj"),
         # generic objs usually come from inventories
-        "obj": domains.ObjType("object", "obj")
+        "obj": domains.ObjType("object", "obj"),
     }
 
     # This controls: