sphinxdocs: allow files to be xref (#2897)

This allows files to be specified as xrefs. Also adds a test for the
functionality.

Author: rickeylev

sphinxdocs/src/sphinx_bzl/bzl.py

@@ -502,7 +502,39 @@ 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):
@@ -1493,7 +1525,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:

sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py

@@ -65,7 +65,8 @@ def _doc_element(self, doc):
         ("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):

sphinxdocs/tests/sphinx_stardoc/xrefs.md

@@ -46,3 +46,8 @@ Various tests of cross referencing support
 
 * 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`