8000 sphinxdocs: allow files to be xref (#2897) · vonschultz/rules_python@53fd252 · GitHub
[go: up one dir, main page]
Skip to content

Commit 53fd252

Browse files
rickeylevrickeylev
authored
sphinxdocs: allow files to be xref (bazel-contrib#2897)
This allows files to be specified as xrefs. Also adds a test for the functionality.
1 parent 5c20268 commit 53fd252

File tree

3 files changed

+41
-3
lines changed
  • sphinxdocs

3 files changed

+41
-3
lines changed

‎sphinxdocs/src/sphinx_bzl/bzl.py

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -502,7 +502,39 @@ def run(self) -> list[docutils_nodes.Node]:
502502
self.env.ref_context["bzl:file"] = file_label
503503
self.env.ref_context["bzl:object_id_stack"] = []
504504
self.env.ref_context["bzl:doc_id_stack"] = []
505-
return []
505+
506+
_, _, basename = file_label.partition(":")
507+
index_description = f"File {label}"
508+
absolute_label = repo + label
509+
self.env.get_domain("bzl").add_object(
510+
_ObjectEntry(
511+
full_id=absolute_label,
512+
display_name=absolute_label,
513+
object_type="obj",
514+
search_priority=1,
515+
index_entry=domains.IndexEntry(
516+
name=basename,
517+
subtype=_INDEX_SUBTYPE_NORMAL,
518+
docname=self.env.docname,
519+
anchor="",
520+
extra="",
521+
qualifier="",
522+
descr=index_description,
523+
),
524+
),
525+
alt_names=[
526+
# Allow xref //foo:bar.bzl
527+
file_label,
528+
# Allow xref bar.bzl
529+
8000 basename,
530+
],
531+
)
532+
index_node = addnodes.index(
533+
entries=[
534+
_index_node_tuple("single", f"File; {label}", ""),
535+
]
536+
)
537+
return [index_node]
506538

507539

508540
class _BzlAttrInfo(sphinx_docutils.SphinxDirective):
@@ -1493,7 +1525,7 @@ class _BzlDomain(domains.Domain):
14931525
"type": domains.ObjType("type", "type", "obj"),
14941526
"typedef": domains.ObjType("typedef", "typedef", "type", "obj"),
14951527
# generic objs usually come from inventories
1496-
"obj": domains.ObjType("object", "obj")
1528+
"obj": domains.ObjType("object", "obj"),
14971529
}
14981530

14991531
# This controls:

‎sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ def _doc_element(self, doc):
6565
("full_repo_target", "@testrepo//lang:relativetarget", "target.html#relativetarget"),
6666
("tag_class_attr_using_attr_role", "myext.mytag.ta1", "module_extension.html#myext.mytag.ta1"),
6767
("tag_class_attr_using_attr_role_just_attr_name", "ta1", "module_extension.html#myext.mytag.ta1"),
68-
68+
("file_without_repo", "//lang:rule.bzl", "rule.html"),
69+
("file_with_repo", "@testrepo//lang:rule.bzl", "rule.html"),
6970
# fmt: on
7071
)
7172
def test_xrefs(self, text, href):

‎sphinxdocs/tests/sphinx_stardoc/xrefs.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,8 @@ Various tests of cross referencing support
4646

4747
* tag class attribute using attr role: {attr}`myext.mytag.ta1`
4848
* tag class attribute, just attr name, attr role: {attr}`ta1`
49+
50+
## File refs
51+
52+
* without repo {obj}`//lang:rule.bzl`
53+
* with repo {obj}`@testrepo//lang:rule.bzl`

0 commit comments

Comments
 (0)
0