| # Copyright 2024 The Bazel Authors. All rights reserved. |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| """Sphinx extension for documenting Bazel/Starlark objects.""" |
| |
| import ast |
| import collections |
| import enum |
| import os |
| import typing |
| from collections.abc import Collection |
| from typing import Callable, Iterable, TypeVar |
| |
| from docutils import nodes as docutils_nodes |
| from docutils.parsers.rst import directives as docutils_directives |
| from docutils.parsers.rst import states |
| from sphinx import addnodes, builders |
| from sphinx import directives as sphinx_directives |
| from sphinx import domains, environment, roles |
| from sphinx.highlighting import lexer_classes |
| from sphinx.locale import _ |
| from sphinx.util import docfields |
| from sphinx.util import docutils as sphinx_docutils |
| from sphinx.util import inspect, logging |
| from sphinx.util import nodes as sphinx_nodes |
| from sphinx.util import typing as sphinx_typing |
| from typing_extensions import TypeAlias, override |
| |
| _logger = logging.getLogger(__name__) |
| _LOG_PREFIX = f"[{_logger.name}] " |
| |
| _INDEX_SUBTYPE_NORMAL = 0 |
| _INDEX_SUBTYPE_ENTRY_WITH_SUB_ENTRIES = 1 |
| _INDEX_SUBTYPE_SUB_ENTRY = 2 |
| |
| _T = TypeVar("_T") |
| |
| # See https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.Domain.get_objects |
| _GetObjectsTuple: TypeAlias = tuple[str, str, str, str, str, int] |
| |
| # See SphinxRole.run definition; the docs for role classes are pretty sparse. |
| _RoleRunResult: TypeAlias = tuple[ |
| list[docutils_nodes.Node], list[docutils_nodes.system_message] |
| ] |
| |
| |
| def _log_debug(message, *args): |
| # NOTE: Non-warning log messages go to stdout and are only |
| # visible when -q isn't passed to Sphinx. Note that the sphinx_docs build |
| # rule passes -q by default; use --//sphinxdocs:quiet=false to disable it. |
| _logger.debug("%s" + message, _LOG_PREFIX, *args) |
| |
| |
| def _position_iter(values: Collection[_T]) -> tuple[bool, bool, _T]: |
| last_i = len(values) - 1 |
| for i, value in enumerate(values): |
| yield i == 0, i == last_i, value |
| |
| |
| class InvalidValueError(Exception): |
| """Generic error for an invalid value instead of ValueError. |
| |
| Sphinx treats regular ValueError to mean abort parsing the current |
| chunk and continue on as best it can. Their error means a more |
| fundamental problem that should cause a failure. |
| """ |
| |
| |
| class _ObjectEntry: |
| """Metadata about a known object.""" |
| |
| def __init__( |
| self, |
| full_id: str, |
| display_name: str, |
| object_type: str, |
| search_priority: int, |
| index_entry: domains.IndexEntry, |
| ): |
| """Creates an instance. |
| |
| Args: |
| full_id: The fully qualified id of the object. Should be |
| globally unique, even between projects. |
| display_name: What to display the object as in casual context. |
| object_type: The type of object, typically one of the values |
| known to the domain. |
| search_priority: The search priority, see |
| https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.Domain.get_objects |
| for valid values. |
| index_entry: Metadata about the object for the domain index. |
| """ |
| self.full_id = full_id |
| self.display_name = display_name |
| self.object_type = object_type |
| self.search_priority = search_priority |
| self.index_entry = index_entry |
| |
| def to_get_objects_tuple(self) -> _GetObjectsTuple: |
| # For the tuple definition |
| return ( |
| self.full_id, |
| self.display_name, |
| self.object_type, |
| self.index_entry.docname, |
| self.index_entry.anchor, |
| self.search_priority, |
| ) |
| |
| def __repr__(self): |
| return f"ObjectEntry({self.full_id=}, {self.object_type=}, {self.display_name=}, {self.index_entry.docname=})" |
| |
| |
| # A simple helper just to document what the index tuple nodes are. |
| def _index_node_tuple( |
| entry_type: str, |
| entry_name: str, |
| target: str, |
| main: typing.Union[str, None] = None, |
| category_key: typing.Union[str, None] = None, |
| ) -> tuple[str, str, str, typing.Union[str, None], typing.Union[str, None]]: |
| # For this tuple definition, see: |
| # https://www.sphinx-doc.org/en/master/extdev/nodes.html#sphinx.addnodes.index |
| # For the definition of entry_type, see: |
| # And https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index |
| return (entry_type, entry_name, target, main, category_key) |
| |
| |
| class _BzlObjectId: |
| """Identifies an object defined by a directive. |
| |
| This object is returned by `handle_signature()` and passed onto |
| `add_target_and_index()`. It contains information to identify the object |
| that is being described so that it can be indexed and tracked by the |
| domain. |
| """ |
| |
| def __init__( |
| self, |
| *, |
| repo: str, |
| label: str, |
| namespace: str = None, |
| symbol: str = None, |
| ): |
| """Creates an instance. |
| |
| Args: |
| repo: repository name, including leading "@". |
| bzl_file: label of file containing the object, e.g. //foo:bar.bzl |
| namespace: dotted name of the namespace the symbol is within. |
| symbol: dotted name, relative to `namespace` of the symbol. |
| """ |
| if not repo: |
| raise InvalidValueError("repo cannot be empty") |
| if not repo.startswith("@"): |
| raise InvalidValueError("repo must start with @") |
| if not label: |
| raise InvalidValueError("label cannot be empty") |
| if not label.startswith("//"): |
| raise InvalidValueError("label must start with //") |
| |
| if not label.endswith(".bzl") and (symbol or namespace): |
| raise InvalidValueError( |
| "Symbol and namespace can only be specified for .bzl labels" |
| ) |
| |
| self.repo = repo |
| self.label = label |
| self.package, self.target_name = self.label.split(":") |
| self.namespace = namespace |
| self.symbol = symbol # Relative to namespace |
| # doc-relative identifier for this object |
| self.doc_id = symbol or self.target_name |
| |
| if not self.doc_id: |
| raise InvalidValueError("doc_id is empty") |
| |
| self.full_id = _full_id_from_parts(repo, label, [namespace, symbol]) |
| |
| @classmethod |
| def from_env( |
| cls, env: environment.BuildEnvironment, *, symbol: str = None, label: str = None |
| ) -> "_BzlObjectId": |
| label = label or env.ref_context["bzl:file"] |
| if symbol: |
| namespace = ".".join(env.ref_context["bzl:doc_id_stack"]) |
| else: |
| namespace = None |
| |
| return cls( |
| repo=env.ref_context["bzl:repo"], |
| label=label, |
| namespace=namespace, |
| symbol=symbol, |
| ) |
| |
| def __repr__(self): |
| return f"_BzlObjectId({self.full_id=})" |
| |
| |
| def _full_id_from_env(env, object_ids=None): |
| return _full_id_from_parts( |
| env.ref_context["bzl:repo"], |
| env.ref_context["bzl:file"], |
| env.ref_context["bzl:object_id_stack"] + (object_ids or []), |
| ) |
| |
| |
| def _full_id_from_parts(repo, bzl_file, symbol_names=None): |
| parts = [repo, bzl_file] |
| |
| symbol_names = symbol_names or [] |
| symbol_names = list(filter(None, symbol_names)) # Filter out empty values |
| if symbol_names: |
| parts.append("%") |
| parts.append(".".join(symbol_names)) |
| |
| full_id = "".join(parts) |
| return full_id |
| |
| |
| def _parse_full_id(full_id): |
| repo, slashes, label = full_id.partition("//") |
| label = slashes + label |
| label, _, symbol = label.partition("%") |
| return (repo, label, symbol) |
| |
| |
| class _TypeExprParser(ast.NodeVisitor): |
| """Parsers a string description of types to doc nodes.""" |
| |
| def __init__(self, make_xref: Callable[[str], docutils_nodes.Node]): |
| self.root_node = addnodes.desc_inline("bzl", classes=["type-expr"]) |
| self.make_xref = make_xref |
| self._doc_node_stack = [self.root_node] |
| |
| @classmethod |
| def xrefs_from_type_expr( |
| cls, |
| type_expr_str: str, |
| make_xref: Callable[[str], docutils_nodes.Node], |
| ) -> docutils_nodes.Node: |
| module = ast.parse(type_expr_str) |
| visitor = cls(make_xref) |
| visitor.visit(module.body[0]) |
| return visitor.root_node |
| |
| def _append(self, node: docutils_nodes.Node): |
| self._doc_node_stack[-1] += node |
| |
| def _append_and_push(self, node: docutils_nodes.Node): |
| self._append(node) |
| self._doc_node_stack.append(node) |
| |
| def visit_Attribute(self, node: ast.Attribute): |
| current = node |
| parts = [] |
| while current: |
| if isinstance(current, ast.Attribute): |
| parts.append(current.attr) |
| current = current.value |
| elif isinstance(current, ast.Name): |
| parts.append(current.id) |
| break |
| else: |
| raise InvalidValueError(f"Unexpected Attribute.value node: {current}") |
| dotted_name = ".".join(reversed(parts)) |
| self._append(self.make_xref(dotted_name)) |
| |
| def visit_Constant(self, node: ast.Constant): |
| if node.value is None: |
| self._append(self.make_xref("None")) |
| elif isinstance(node.value, str): |
| self._append(self.make_xref(node.value)) |
| else: |
| raise InvalidValueError( |
| f"Unexpected Constant node value: ({type(node.value)}) {node.value=}" |
| ) |
| |
| def visit_Name(self, node: ast.Name): |
| xref_node = self.make_xref(node.id) |
| self._append(xref_node) |
| |
| def visit_BinOp(self, node: ast.BinOp): |
| self.visit(node.left) |
| self._append(addnodes.desc_sig_space()) |
| if isinstance(node.op, ast.BitOr): |
| self._append(addnodes.desc_sig_punctuation("", "|")) |
| else: |
| raise InvalidValueError(f"Unexpected BinOp: {node}") |
| self._append(addnodes.desc_sig_space()) |
| self.visit(node.right) |
| |
| def visit_Expr(self, node: ast.Expr): |
| self.visit(node.value) |
| |
| def visit_Subscript(self, node: ast.Subscript): |
| self.visit(node.value) |
| self._append_and_push(addnodes.desc_type_parameter_list()) |
| self.visit(node.slice) |
| self._doc_node_stack.pop() |
| |
| def visit_Tuple(self, node: ast.Tuple): |
| for element in node.elts: |
| self._append_and_push(addnodes.desc_type_parameter()) |
| self.visit(element) |
| self._doc_node_stack.pop() |
| |
| def visit_List(self, node: ast.List): |
| self._append_and_push(addnodes.desc_type_parameter_list()) |
| for element in node.elts: |
| self._append_and_push(addnodes.desc_type_parameter()) |
| self.visit(element) |
| self._doc_node_stack.pop() |
| |
| @override |
| def generic_visit(self, node): |
| raise InvalidValueError(f"Unexpected ast node: {type(node)} {node}") |
| |
| |
| class _BzlXrefField(docfields.Field): |
| """Abstract base class to create cross references for fields.""" |
| |
| @override |
| def make_xrefs( |
| self, |
| rolename: str, |
| domain: str, |
| target: str, |
| innernode: type[sphinx_typing.TextlikeNode] = addnodes.literal_emphasis, |
| contnode: typing.Union[docutils_nodes.Node, None] = None, |
| env: typing.Union[environment.BuildEnvironment, None] = None, |
| inliner: typing.Union[states.Inliner, None] = None, |
| location: typing.Union[docutils_nodes.Element, None] = None, |
| ) -> list[docutils_nodes.Node]: |
| if rolename in ("arg", "attr"): |
| return self._make_xrefs_for_arg_attr( |
| rolename, domain, target, innernode, contnode, env, inliner, location |
| ) |
| else: |
| return super().make_xrefs( |
| rolename, domain, target, innernode, contnode, env, inliner, location |
| ) |
| |
| def _make_xrefs_for_arg_attr( |
| self, |
| rolename: str, |
| domain: str, |
| arg_name: str, |
| innernode: type[sphinx_typing.TextlikeNode] = addnodes.literal_emphasis, |
| contnode: typing.Union[docutils_nodes.Node, None] = None, |
| env: typing.Union[environment.BuildEnvironment, None] = None, |
| inliner: typing.Union[states.Inliner, None] = None, |
| location: typing.Union[docutils_nodes.Element, None] = None, |
| ) -> list[docutils_nodes.Node]: |
| bzl_file = env.ref_context["bzl:file"] |
| anchor_prefix = ".".join(env.ref_context["bzl:doc_id_stack"]) |
| if not anchor_prefix: |
| raise InvalidValueError( |
| f"doc_id_stack empty when processing arg {arg_name}" |
| ) |
| index_description = f"{arg_name} ({self.name} in {bzl_file}%{anchor_prefix})" |
| anchor_id = f"{anchor_prefix}.{arg_name}" |
| full_id = _full_id_from_env(env, [arg_name]) |
| |
| env.get_domain(domain).add_object( |
| _ObjectEntry( |
| full_id=full_id, |
| display_name=arg_name, |
| object_type=self.name, |
| search_priority=1, |
| index_entry=domains.IndexEntry( |
| name=arg_name, |
| subtype=_INDEX_SUBTYPE_NORMAL, |
| docname=env.docname, |
| anchor=anchor_id, |
| extra="", |
| qualifier="", |
| descr=index_description, |
| ), |
| ), |
| # This allows referencing an arg as e.g `funcname.argname` |
| alt_names=[anchor_id], |
| ) |
| |
| # Two changes to how arg xrefs are created: |
| # 2. Use the full id instead of base name. This makes it unambiguous |
| # as to what it's referencing. |
| pending_xref = super().make_xref( |
| # The full_id is used as the target so its unambiguious. |
| rolename, |
| domain, |
| f"{arg_name} <{full_id}>", |
| innernode, |
| contnode, |
| env, |
| inliner, |
| location, |
| ) |
| |
| wrapper = docutils_nodes.inline(ids=[anchor_id]) |
| |
| index_node = addnodes.index( |
| entries=[ |
| _index_node_tuple( |
| "single", f"{self.name}; {index_description}", anchor_id |
| ), |
| _index_node_tuple("single", index_description, anchor_id), |
| ] |
| ) |
| wrapper += index_node |
| wrapper += pending_xref |
| return [wrapper] |
| |
| |
| class _BzlDocField(_BzlXrefField, docfields.Field): |
| """A non-repeated field with xref support.""" |
| |
| |
| class _BzlGroupedField(_BzlXrefField, docfields.GroupedField): |
| """A repeated fieled grouped as a list with xref support.""" |
| |
| |
| class _BzlCsvField(_BzlXrefField): |
| """Field with a CSV list of values.""" |
| |
| def __init__(self, *args, body_domain: str = "", **kwargs): |
| super().__init__(*args, **kwargs) |
| self._body_domain = body_domain |
| |
| def make_field( |
| self, |
| types: dict[str, list[docutils_nodes.Node]], |
| domain: str, |
| item: tuple, |
| env: environment.BuildEnvironment = None, |
| inliner: typing.Union[states.Inliner, None] = None, |
| location: typing.Union[docutils_nodes.Element, None] = None, |
| ) -> docutils_nodes.field: |
| field_text = item[1][0].astext() |
| parts = [p.strip() for p in field_text.split(",")] |
| field_body = docutils_nodes.field_body() |
| for _, is_last, part in _position_iter(parts): |
| node = self.make_xref( |
| self.bodyrolename, |
| self._body_domain or domain, |
| part, |
| env=env, |
| inliner=inliner, |
| location=location, |
| ) |
| field_body += node |
| if not is_last: |
| field_body += docutils_nodes.Text(", ") |
| |
| field_name = docutils_nodes.field_name("", self.label) |
| return docutils_nodes.field("", field_name, field_body) |
| |
| |
| class _BzlCurrentFile(sphinx_docutils.SphinxDirective): |
| """Sets what bzl file following directives are defined in. |
| |
| The directive's argument is an absolute Bazel label, e.g. `//foo:bar.bzl` |
| or `@repo//foo:bar.bzl`. The repository portion is optional; if specified, |
| it will override the `bzl_default_repository_name` configuration setting. |
| |
| Example MyST usage |
| |
| ``` |
| :::{bzl:currentfile} //my:file.bzl |
| ::: |
| ``` |
| """ |
| |
| has_content = False |
| required_arguments = 1 |
| final_argument_whitespace = False |
| |
| @override |
| def run(self) -> list[docutils_nodes.Node]: |
| label = self.arguments[0].strip() |
| repo, slashes, file_label = label.partition("//") |
| file_label = slashes + file_label |
| if not repo: |
| repo = self.env.config.bzl_default_repository_name |
| self.env.ref_context["bzl:repo"] = repo |
| 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 [] |
| |
| |
| class _BzlAttrInfo(sphinx_docutils.SphinxDirective): |
| has_content = False |
| required_arguments = 1 |
| optional_arguments = 0 |
| option_spec = { |
| "executable": docutils_directives.flag, |
| "mandatory": docutils_directives.flag, |
| } |
| |
| def run(self): |
| content_node = docutils_nodes.paragraph("", "") |
| content_node += docutils_nodes.paragraph( |
| "", "mandatory" if "mandatory" in self.options else "optional" |
| ) |
| if "executable" in self.options: |
| content_node += docutils_nodes.paragraph("", "Must be an executable") |
| |
| return [content_node] |
| |
| |
| class _BzlObject(sphinx_directives.ObjectDescription[_BzlObjectId]): |
| """Base class for describing a Bazel/Starlark object. |
| |
| This directive takes a single argument: a string name with optional |
| function signature. |
| |
| * The name can be a dotted name, e.g. `a.b.foo` |
| * The signature is in Python signature syntax, e.g. `foo(a=x) -> R` |
| * The signature supports default values. |
| * Arg type annotations are not supported; use `{bzl:type}` instead as |
| part of arg/attr documentation. |
| |
| Example signatures: |
| * `foo` |
| * `foo(arg1, arg2)` |
| * `foo(arg1, arg2=default) -> returntype` |
| """ |
| |
| option_spec = sphinx_directives.ObjectDescription.option_spec | { |
| "origin-key": docutils_directives.unchanged, |
| } |
| |
| @override |
| def before_content(self) -> None: |
| symbol_name = self.names[-1].symbol |
| if symbol_name: |
| self.env.ref_context["bzl:object_id_stack"].append(symbol_name) |
| self.env.ref_context["bzl:doc_id_stack"].append(symbol_name) |
| |
| @override |
| def transform_content(self, content_node: addnodes.desc_content) -> None: |
| def first_child_with_class_name( |
| root, class_name |
| ) -> typing.Union[None, docutils_nodes.Element]: |
| matches = root.findall( |
| lambda node: isinstance(node, docutils_nodes.Element) |
| and class_name in node["classes"] |
| ) |
| found = next(matches, None) |
| return found |
| |
| def match_arg_field_name(node): |
| # fmt: off |
| return ( |
| isinstance(node, docutils_nodes.field_name) |
| and node.astext().startswith(("arg ", "attr ")) |
| ) |
| # fmt: on |
| |
| # Move the spans for the arg type and default value to be first. |
| arg_name_fields = list(content_node.findall(match_arg_field_name)) |
| for arg_name_field in arg_name_fields: |
| arg_body_field = arg_name_field.next_node(descend=False, siblings=True) |
| # arg_type_node = first_child_with_class_name(arg_body_field, "arg-type-span") |
| arg_type_node = first_child_with_class_name(arg_body_field, "type-expr") |
| arg_default_node = first_child_with_class_name( |
| arg_body_field, "default-value-span" |
| ) |
| |
| # Inserting into the body field itself causes the elements |
| # to be grouped into the paragraph node containing the arg |
| # name (as opposed to the paragraph node containing the |
| # doc text) |
| |
| if arg_default_node: |
| arg_default_node.parent.remove(arg_default_node) |
| arg_body_field.insert(0, arg_default_node) |
| |
| if arg_type_node: |
| arg_type_node.parent.remove(arg_type_node) |
| decorated_arg_type_node = docutils_nodes.inline( |
| "", |
| "", |
| docutils_nodes.Text("("), |
| arg_type_node, |
| docutils_nodes.Text(") "), |
| classes=["arg-type-span"], |
| ) |
| # arg_body_field.insert(0, arg_type_node) |
| arg_body_field.insert(0, decorated_arg_type_node) |
| |
| @override |
| def after_content(self) -> None: |
| if self.names[-1].symbol: |
| self.env.ref_context["bzl:object_id_stack"].pop() |
| self.env.ref_context["bzl:doc_id_stack"].pop() |
| |
| # docs on how to build signatures: |
| # https://www.sphinx-doc.org/en/master/extdev/nodes.html#sphinx.addnodes.desc_signature |
| @override |
| def handle_signature( |
| self, sig_text: str, sig_node: addnodes.desc_signature |
| ) -> _BzlObjectId: |
| self._signature_add_object_type(sig_node) |
| |
| relative_name, lparen, params_text = sig_text.partition("(") |
| if lparen: |
| params_text = lparen + params_text |
| |
| relative_name = relative_name.strip() |
| |
| name_prefix, _, base_symbol_name = relative_name.rpartition(".") |
| |
| if name_prefix: |
| # Respect whatever the signature wanted |
| display_prefix = name_prefix |
| else: |
| # Otherwise, show the outermost name. This makes ctrl+f finding |
| # for a symbol a bit easier. |
| display_prefix = ".".join(self.env.ref_context["bzl:doc_id_stack"]) |
| _, _, display_prefix = display_prefix.rpartition(".") |
| |
| if display_prefix: |
| display_prefix = display_prefix + "." |
| sig_node += addnodes.desc_addname(display_prefix, display_prefix) |
| sig_node += addnodes.desc_name(base_symbol_name, base_symbol_name) |
| |
| if type_expr := self.options.get("type"): |
| |
| def make_xref(name, title=None): |
| content_node = addnodes.desc_type(name, name) |
| return addnodes.pending_xref( |
| "", |
| content_node, |
| refdomain="bzl", |
| reftype="type", |
| reftarget=name, |
| ) |
| |
| attr_annotation_node = addnodes.desc_annotation( |
| type_expr, |
| "", |
| addnodes.desc_sig_punctuation("", ":"), |
| addnodes.desc_sig_space(), |
| _TypeExprParser.xrefs_from_type_expr(type_expr, make_xref), |
| ) |
| sig_node += attr_annotation_node |
| |
| if params_text: |
| try: |
| signature = inspect.signature_from_str(params_text) |
| except SyntaxError: |
| # Stardoc doesn't provide accurate info, so the reconstructed |
| # signature might not be valid syntax. Rather than fail, just |
| # provide a plain-text description of the approximate signature. |
| # See https://github.com/bazelbuild/stardoc/issues/225 |
| sig_node += addnodes.desc_parameterlist( |
| # Offset by 1 to remove the surrounding parentheses |
| params_text[1:-1], |
| params_text[1:-1], |
| ) |
| else: |
| last_kind = None |
| paramlist_node = addnodes.desc_parameterlist() |
| for param in signature.parameters.values(): |
| if param.kind == param.KEYWORD_ONLY and last_kind in ( |
| param.POSITIONAL_OR_KEYWORD, |
| param.POSITIONAL_ONLY, |
| None, |
| ): |
| # Add separator for keyword only parameter: * |
| paramlist_node += addnodes.desc_parameter( |
| "", "", addnodes.desc_sig_operator("", "*") |
| ) |
| |
| last_kind = param.kind |
| node = addnodes.desc_parameter() |
| if param.kind == param.VAR_POSITIONAL: |
| node += addnodes.desc_sig_operator("", "*") |
| elif param.kind == param.VAR_KEYWORD: |
| node += addnodes.desc_sig_operator("", "**") |
| |
| node += addnodes.desc_sig_name(rawsource="", text=param.name) |
| if param.default is not param.empty: |
| node += addnodes.desc_sig_operator("", "=") |
| node += docutils_nodes.inline( |
| "", |
| param.default, |
| classes=["default_value"], |
| support_smartquotes=False, |
| ) |
| paramlist_node += node |
| sig_node += paramlist_node |
| |
| if signature.return_annotation is not signature.empty: |
| sig_node += addnodes.desc_returns("", signature.return_annotation) |
| |
| obj_id = _BzlObjectId.from_env(self.env, symbol=relative_name) |
| |
| sig_node["bzl:object_id"] = obj_id.full_id |
| return obj_id |
| |
| def _signature_add_object_type(self, sig_node: addnodes.desc_signature): |
| if sig_object_type := self._get_signature_object_type(): |
| sig_node += addnodes.desc_annotation("", self._get_signature_object_type()) |
| sig_node += addnodes.desc_sig_space() |
| |
| @override |
| def add_target_and_index( |
| self, obj_desc: _BzlObjectId, sig: str, sig_node: addnodes.desc_signature |
| ) -> None: |
| super().add_target_and_index(obj_desc, sig, sig_node) |
| if obj_desc.symbol: |
| display_name = obj_desc.symbol |
| location = obj_desc.label |
| if obj_desc.namespace: |
| location += f"%{obj_desc.namespace}" |
| else: |
| display_name = obj_desc.target_name |
| location = obj_desc.package |
| |
| anchor_prefix = ".".join(self.env.ref_context["bzl:doc_id_stack"]) |
| if anchor_prefix: |
| anchor_id = f"{anchor_prefix}.{obj_desc.doc_id}" |
| else: |
| anchor_id = obj_desc.doc_id |
| |
| sig_node["ids"].append(anchor_id) |
| |
| object_type_display = self._get_object_type_display_name() |
| index_description = f"{display_name} ({object_type_display} in {location})" |
| self.indexnode["entries"].extend( |
| _index_node_tuple("single", f"{index_type}; {index_description}", anchor_id) |
| for index_type in [object_type_display] + self._get_additional_index_types() |
| ) |
| self.indexnode["entries"].append( |
| _index_node_tuple("single", index_description, anchor_id), |
| ) |
| |
| object_entry = _ObjectEntry( |
| full_id=obj_desc.full_id, |
| display_name=display_name, |
| object_type=self.objtype, |
| search_priority=1, |
| index_entry=domains.IndexEntry( |
| name=display_name, |
| subtype=_INDEX_SUBTYPE_NORMAL, |
| docname=self.env.docname, |
| anchor=anchor_id, |
| extra="", |
| qualifier="", |
| descr=index_description, |
| ), |
| ) |
| |
| alt_names = [] |
| if origin_key := self.options.get("origin-key"): |
| alt_names.append( |
| origin_key |
| # Options require \@ for leading @, but don't |
| # remove the escaping slash, so we have to do it manually |
| .lstrip("\\") |
| ) |
| extra_alt_names = self._get_alt_names(object_entry) |
| alt_names.extend(extra_alt_names) |
| |
| self.env.get_domain(self.domain).add_object(object_entry, alt_names=alt_names) |
| |
| def _get_additional_index_types(self): |
| return [] |
| |
| @override |
| def _object_hierarchy_parts( |
| self, sig_node: addnodes.desc_signature |
| ) -> tuple[str, ...]: |
| return _parse_full_id(sig_node["bzl:object_id"]) |
| |
| @override |
| def _toc_entry_name(self, sig_node: addnodes.desc_signature) -> str: |
| return sig_node["_toc_parts"][-1] |
| |
| def _get_object_type_display_name(self) -> str: |
| return self.env.get_domain(self.domain).object_types[self.objtype].lname |
| |
| def _get_signature_object_type(self) -> str: |
| return self._get_object_type_display_name() |
| |
| def _get_alt_names(self, object_entry): |
| alt_names = [] |
| full_id = object_entry.full_id |
| label, _, symbol = full_id.partition("%") |
| if symbol: |
| # Allow referring to the file-relative fully qualified symbol name |
| alt_names.append(symbol) |
| if "." in symbol: |
| # Allow referring to the last component of the symbol |
| alt_names.append(symbol.split(".")[-1]) |
| else: |
| # Otherwise, it's a target. Allow referring to just the target name |
| _, _, target_name = label.partition(":") |
| alt_names.append(target_name) |
| |
| return alt_names |
| |
| |
| class _BzlCallable(_BzlObject): |
| """Abstract base class for objects that are callable.""" |
| |
| |
| class _BzlTypedef(_BzlObject): |
| """Documents a typedef. |
| |
| A typedef describes objects with well known attributes. |
| |
| ````` |
| ::::{bzl:typedef} Square |
| |
| :::{bzl:field} width |
| :type: int |
| ::: |
| |
| :::{bzl:function} new(size) |
| ::: |
| |
| :::{bzl:function} area() |
| ::: |
| :::: |
| ````` |
| """ |
| |
| |
| class _BzlProvider(_BzlObject): |
| """Documents a provider type. |
| |
| Example MyST usage |
| |
| ``` |
| ::::{bzl:provider} MyInfo |
| |
| Docs about MyInfo |
| |
| :::{bzl:provider-field} some_field |
| :type: depset[str] |
| ::: |
| :::: |
| ``` |
| """ |
| |
| |
| class _BzlField(_BzlObject): |
| """Documents a field of a provider. |
| |
| Fields can optionally have a type specified using the `:type:` option. |
| |
| The type can be any type expression understood by the `{bzl:type}` role. |
| |
| ``` |
| :::{bzl:provider-field} foo |
| :type: str |
| ::: |
| ``` |
| """ |
| |
| option_spec = _BzlObject.option_spec.copy() |
| option_spec.update( |
| { |
| "type": docutils_directives.unchanged, |
| } |
| ) |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| return "" |
| |
| @override |
| def _get_alt_names(self, object_entry): |
| alt_names = super()._get_alt_names(object_entry) |
| _, _, symbol = object_entry.full_id.partition("%") |
| # Allow refering to `mod_ext_name.tag_name`, even if the extension |
| # is nested within another object |
| alt_names.append(".".join(symbol.split(".")[-2:])) |
| return alt_names |
| |
| |
| class _BzlProviderField(_BzlField): |
| pass |
| |
| |
| class _BzlRepositoryRule(_BzlCallable): |
| """Documents a repository rule. |
| |
| Doc fields: |
| * attr: Documents attributes of the rule. Takes a single arg, the |
| attribute name. Can be repeated. The special roles `{default-value}` |
| and `{arg-type}` can be used to indicate the default value and |
| type of attribute, respectively. |
| * environment-variables: a CSV list of environment variable names. |
| They will be cross referenced with matching environment variables. |
| |
| Example MyST usage |
| |
| ``` |
| :::{bzl:repo-rule} myrule(foo) |
| |
| :attr foo: {default-value}`"foo"` {arg-type}`attr.string` foo doc string |
| |
| :environment-variables: FOO, BAR |
| ::: |
| ``` |
| """ |
| |
| doc_field_types = [ |
| _BzlGroupedField( |
| "attr", |
| label=_("Attributes"), |
| names=["attr"], |
| rolename="attr", |
| can_collapse=False, |
| ), |
| _BzlCsvField( |
| "environment-variables", |
| label=_("Environment Variables"), |
| names=["environment-variables"], |
| body_domain="std", |
| bodyrolename="envvar", |
| has_arg=False, |
| ), |
| ] |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| return "repo rule" |
| |
| |
| class _BzlRule(_BzlCallable): |
| """Documents a rule. |
| |
| Doc fields: |
| * attr: Documents attributes of the rule. Takes a single arg, the |
| attribute name. Can be repeated. The special roles `{default-value}` |
| and `{arg-type}` can be used to indicate the default value and |
| type of attribute, respectively. |
| * provides: A type expression of the provider types the rule provides. |
| To indicate different groupings, use `|` and `[]`. For example, |
| `FooInfo | [BarInfo, BazInfo]` means it provides either `FooInfo` |
| or both of `BarInfo` and `BazInfo`. |
| |
| Example MyST usage |
| |
| ``` |
| :::{bzl:repo-rule} myrule(foo) |
| |
| :attr foo: {default-value}`"foo"` {arg-type}`attr.string` foo doc string |
| |
| :provides: FooInfo | BarInfo |
| ::: |
| ``` |
| """ |
| |
| doc_field_types = [ |
| _BzlGroupedField( |
| "attr", |
| label=_("Attributes"), |
| names=["attr"], |
| rolename="attr", |
| can_collapse=False, |
| ), |
| _BzlDocField( |
| "provides", |
| label="Provides", |
| has_arg=False, |
| names=["provides"], |
| bodyrolename="type", |
| ), |
| ] |
| |
| |
| class _BzlAspect(_BzlObject): |
| """Documents an aspect. |
| |
| Doc fields: |
| * attr: Documents attributes of the aspect. Takes a single arg, the |
| attribute name. Can be repeated. The special roles `{default-value}` |
| and `{arg-type}` can be used to indicate the default value and |
| type of attribute, respectively. |
| * aspect-attributes: A CSV list of attribute names the aspect |
| propagates along. |
| |
| Example MyST usage |
| |
| ``` |
| :::{bzl:repo-rule} myaspect |
| |
| :attr foo: {default-value}`"foo"` {arg-type}`attr.string` foo doc string |
| |
| :aspect-attributes: srcs, deps |
| ::: |
| ``` |
| """ |
| |
| doc_field_types = [ |
| _BzlGroupedField( |
| "attr", |
| label=_("Attributes"), |
| names=["attr"], |
| rolename="attr", |
| can_collapse=False, |
| ), |
| _BzlCsvField( |
| "aspect-attributes", |
| label=_("Aspect Attributes"), |
| names=["aspect-attributes"], |
| has_arg=False, |
| ), |
| ] |
| |
| |
| class _BzlFunction(_BzlCallable): |
| """Documents a general purpose function. |
| |
| Doc fields: |
| * arg: Documents the arguments of the function. Takes a single arg, the |
| arg name. Can be repeated. The special roles `{default-value}` |
| and `{arg-type}` can be used to indicate the default value and |
| type of attribute, respectively. |
| * returns: Documents what the function returns. The special role |
| `{return-type}` can be used to indicate the return type of the function. |
| |
| Example MyST usage |
| |
| ``` |
| :::{bzl:function} myfunc(a, b=None) -> bool |
| |
| :arg a: {arg-type}`str` some arg doc |
| :arg b: {arg-type}`int | None` {default-value}`42` more arg doc |
| :returns: {return-type}`bool` doc about return value. |
| ::: |
| ``` |
| """ |
| |
| doc_field_types = [ |
| _BzlGroupedField( |
| "arg", |
| label=_("Args"), |
| names=["arg"], |
| rolename="arg", |
| can_collapse=False, |
| ), |
| docfields.Field( |
| "returns", |
| label=_("Returns"), |
| has_arg=False, |
| names=["returns"], |
| ), |
| ] |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| return "" |
| |
| |
| class _BzlModuleExtension(_BzlObject): |
| """Documents a module_extension. |
| |
| Doc fields: |
| * os-dependent: Documents if the module extension depends on the host |
| architecture. |
| * arch-dependent: Documents if the module extension depends on the host |
| architecture. |
| * environment-variables: a CSV list of environment variable names. |
| They will be cross referenced with matching environment variables. |
| |
| Tag classes are documented using the bzl:tag-class directives within |
| this directive. |
| |
| Example MyST usage: |
| |
| ``` |
| ::::{bzl:module-extension} myext |
| |
| :os-dependent: True |
| :arch-dependent: False |
| |
| :::{bzl:tag-class} mytag(myattr) |
| |
| :attr myattr: |
| {arg-type}`attr.string_list` |
| doc for attribute |
| ::: |
| :::: |
| ``` |
| """ |
| |
| doc_field_types = [ |
| _BzlDocField( |
| "os-dependent", |
| label="OS Dependent", |
| has_arg=False, |
| names=["os-dependent"], |
| ), |
| _BzlDocField( |
| "arch-dependent", |
| label="Arch Dependent", |
| has_arg=False, |
| names=["arch-dependent"], |
| ), |
| _BzlCsvField( |
| "environment-variables", |
| label=_("Environment Variables"), |
| names=["environment-variables"], |
| body_domain="std", |
| bodyrolename="envvar", |
| has_arg=False, |
| ), |
| ] |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| return "module ext" |
| |
| |
| class _BzlTagClass(_BzlCallable): |
| """Documents a tag class for a module extension. |
| |
| Doc fields: |
| * attr: Documents attributes of the tag class. Takes a single arg, the |
| attribute name. Can be repeated. The special roles `{default-value}` |
| and `{arg-type}` can be used to indicate the default value and |
| type of attribute, respectively. |
| |
| Example MyST usage, note that this directive should be nested with |
| a `bzl:module-extension` directive. |
| |
| ``` |
| :::{bzl:tag-class} mytag(myattr) |
| |
| :attr myattr: |
| {arg-type}`attr.string_list` |
| doc for attribute |
| ::: |
| ``` |
| """ |
| |
| doc_field_types = [ |
| _BzlGroupedField( |
| "arg", |
| label=_("Attributes"), |
| names=["attr"], |
| rolename="arg", |
| can_collapse=False, |
| ), |
| ] |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| return "" |
| |
| @override |
| def _get_alt_names(self, object_entry): |
| alt_names = super()._get_alt_names(object_entry) |
| _, _, symbol = object_entry.full_id.partition("%") |
| # Allow refering to `ProviderName.field`, even if the provider |
| # is nested within another object |
| alt_names.append(".".join(symbol.split(".")[-2:])) |
| return alt_names |
| |
| |
| class _TargetType(enum.Enum): |
| TARGET = "target" |
| FLAG = "flag" |
| |
| |
| class _BzlTarget(_BzlObject): |
| """Documents an arbitrary target.""" |
| |
| _TARGET_TYPE = _TargetType.TARGET |
| |
| def handle_signature(self, sig_text, sig_node): |
| self._signature_add_object_type(sig_node) |
| if ":" in sig_text: |
| package, target_name = sig_text.split(":", 1) |
| else: |
| target_name = sig_text |
| package = self.env.ref_context["bzl:file"] |
| package = package[: package.find(":BUILD")] |
| |
| package = package + ":" |
| if self._TARGET_TYPE == _TargetType.FLAG: |
| sig_node += addnodes.desc_addname("--", "--") |
| sig_node += addnodes.desc_addname(package, package) |
| sig_node += addnodes.desc_name(target_name, target_name) |
| |
| obj_id = _BzlObjectId.from_env(self.env, label=package + target_name) |
| sig_node["bzl:object_id"] = obj_id.full_id |
| return obj_id |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| # We purposely return empty here because having "target" in front |
| # of every label isn't very helpful |
| return "" |
| |
| |
| # TODO: Integrate with the option directive, since flags are options, afterall. |
| # https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-option |
| class _BzlFlag(_BzlTarget): |
| """Documents a flag""" |
| |
| _TARGET_TYPE = _TargetType.FLAG |
| |
| @override |
| def _get_signature_object_type(self) -> str: |
| return "flag" |
| |
| def _get_additional_index_types(self): |
| return ["target"] |
| |
| |
| class _DefaultValueRole(sphinx_docutils.SphinxRole): |
| """Documents the default value for an arg or attribute. |
| |
| This is a special role used within `:arg:` and `:attr:` doc fields to |
| indicate the default value. The rendering process looks for this role |
| and reformats and moves its content for better display. |
| |
| Styling can be customized by matching the `.default_value` class. |
| """ |
| |
| def run(self) -> _RoleRunResult: |
| node = docutils_nodes.emphasis( |
| "", |
| "(default ", |
| docutils_nodes.inline("", self.text, classes=["sig", "default_value"]), |
| docutils_nodes.Text(") "), |
| classes=["default-value-span"], |
| ) |
| return ([node], []) |
| |
| |
| class _TypeRole(sphinx_docutils.SphinxRole): |
| """Documents a type (or type expression) with crossreferencing. |
| |
| This is an inline role used to create cross references to other types. |
| |
| The content is interpreted as a reference to a type or an expression |
| of types. The syntax uses Python-style sytax with `|` and `[]`, e.g. |
| `foo.MyType | str | list[str] | dict[str, int]`. Each symbolic name |
| will be turned into a cross reference; see the domain's documentation |
| for how to reference objects. |
| |
| Example MyST usage: |
| |
| ``` |
| This function accepts {bzl:type}`str | list[str]` for usernames |
| ``` |
| """ |
| |
| def __init__(self): |
| super().__init__() |
| self._xref = roles.XRefRole() |
| |
| def run(self) -> _RoleRunResult: |
| outer_messages = [] |
| |
| def make_xref(name): |
| nodes, msgs = self._xref( |
| "bzl:type", |
| name, |
| name, |
| self.lineno, |
| self.inliner, |
| self.options, |
| self.content, |
| ) |
| outer_messages.extend(msgs) |
| if len(nodes) == 1: |
| return nodes[0] |
| else: |
| return docutils_nodes.inline("", "", nodes) |
| |
| root = _TypeExprParser.xrefs_from_type_expr(self.text, make_xref) |
| return ([root], outer_messages) |
| |
| |
| class _ReturnTypeRole(_TypeRole): |
| """Documents the return type for function. |
| |
| This is a special role used within `:returns:` doc fields to |
| indicate the return type of the function. The rendering process looks for |
| this role and reformats and moves its content for better display. |
| |
| Example MyST Usage |
| |
| ``` |
| :::{bzl:function} foo() |
| |
| :returns: {return-type}`list[str]` |
| ::: |
| ``` |
| """ |
| |
| def run(self) -> _RoleRunResult: |
| nodes, messages = super().run() |
| nodes.append(docutils_nodes.Text(" -- ")) |
| return nodes, messages |
| |
| |
| class _RequiredProvidersRole(_TypeRole): |
| """Documents the providers an attribute requires. |
| |
| This is a special role used within `:arg:` or `:attr:` doc fields to |
| indicate the types of providers that are required. The rendering process |
| looks for this role and reformats its content for better display, but its |
| position is left as-is; typically it would be its own paragraph near the |
| end of the doc. |
| |
| The syntax is a pipe (`|`) delimited list of types or groups of types, |
| where groups are indicated using `[...]`. e.g, to express that FooInfo OR |
| (both of BarInfo and BazInfo) are supported, write `FooInfo | [BarInfo, |
| BazInfo]` |
| |
| Example MyST Usage |
| |
| ``` |
| :::{bzl:rule} foo(bar) |
| |
| :attr bar: My attribute doc |
| |
| {required-providers}`CcInfo | [PyInfo, JavaInfo]` |
| ::: |
| ``` |
| """ |
| |
| def run(self) -> _RoleRunResult: |
| xref_nodes, messages = super().run() |
| nodes = [ |
| docutils_nodes.emphasis("", "Required providers: "), |
| ] + xref_nodes |
| return nodes, messages |
| |
| |
| class _BzlIndex(domains.Index): |
| """An index of a bzl file's objects. |
| |
| NOTE: This generates the entries for the *domain specific* index |
| (bzl-index.html), not the general index (genindex.html). To affect |
| the general index, index nodes and directives must be used (grep |
| for `self.indexnode`). |
| """ |
| |
| name = "index" |
| localname = "Bazel/Starlark Object Index" |
| shortname = "Bzl" |
| |
| def generate( |
| self, docnames: Iterable[str] = None |
| ) -> tuple[list[tuple[str, list[domains.IndexEntry]]], bool]: |
| content = collections.defaultdict(list) |
| |
| # sort the list of objects in alphabetical order |
| objects = self.domain.data["objects"].values() |
| objects = sorted(objects, key=lambda obj: obj.index_entry.name) |
| |
| # Group by first letter |
| for entry in objects: |
| index_entry = entry.index_entry |
| content[index_entry.name[0].lower()].append(index_entry) |
| |
| # convert the dict to the sorted list of tuples expected |
| content = sorted(content.items()) |
| |
| return content, True |
| |
| |
| class _BzlDomain(domains.Domain): |
| """Domain for Bazel/Starlark objects. |
| |
| Directives |
| |
| There are directives for defining Bazel objects and their functionality. |
| See the respective directive classes for details. |
| |
| Public Crossreferencing Roles |
| |
| These are roles that can be used in docs to create cross references. |
| |
| Objects are fully identified using dotted notation converted from the Bazel |
| label and symbol name within a `.bzl` file. The `@`, `/` and `:` characters |
| are converted to dots (with runs removed), and `.bzl` is removed from file |
| names. The dotted path of a symbol in the bzl file is appended. For example, |
| the `paths.join` function in `@bazel_skylib//lib:paths.bzl` would be |
| identified as `bazel_skylib.lib.paths.paths.join`. |
| |
| Shorter identifiers can be used. Within a project, the repo name portion |
| can be omitted. Within a file, file-relative names can be used. |
| |
| * obj: Used to reference a single object without concern for its type. |
| This roles searches all object types for a name that matches the given |
| value. Example usage in MyST: |
| ``` |
| {bzl:obj}`repo.pkg.file.my_function` |
| ``` |
| |
| * type: Transforms a type expression into cross references for objects |
| with object type "type". For example, it parses `int | list[str]` into |
| three links for each component part. |
| |
| Public Typography Roles |
| |
| These are roles used for special purposes to aid documentation. |
| |
| * default-value: The default value for an argument or attribute. Only valid |
| to use within arg or attribute documentation. See `_DefaultValueRole` for |
| details. |
| * required-providers: The providers an attribute requires. Only |
| valud to use within an attribute documentation. See |
| `_RequiredProvidersRole` for details. |
| * return-type: The type of value a function returns. Only valid |
| within a function's return doc field. See `_ReturnTypeRole` for details. |
| |
| Object Types |
| |
| These are the types of objects that this domain keeps in its index. |
| |
| * arg: An argument to a function or macro. |
| * aspect: A Bazel `aspect`. |
| * attribute: An input to a rule (regular, repository, aspect, or module |
| extension). |
| * method: A function bound to an instance of a struct acting as a type. |
| * module-extension: A Bazel `module_extension`. |
| * provider: A Bazel `provider`. |
| * provider-field: A field of a provider. |
| * repo-rule: A Bazel `repository_rule`. |
| * rule: A regular Bazel `rule`. |
| * tag-class: A Bazel `tag_class` of a `module_extension`. |
| * target: A Bazel target. |
| * type: A builtin Bazel type or user-defined structural type. User defined |
| structual types are typically instances `struct` created using a function |
| that acts as a constructor with implicit state bound using closures. |
| """ |
| |
| name = "bzl" |
| label = "Bzl" |
| |
| # NOTE: Most every object type has "obj" as one of the roles because |
| # an object type's role determine what reftypes (cross referencing) can |
| # refer to it. By having "obj" for all of them, it allows writing |
| # :bzl:obj`foo` to restrict object searching to the bzl domain. Under the |
| # hood, this domain translates requests for the :any: role as lookups for |
| # :obj:. |
| # NOTE: We also use these object types for categorizing things in the |
| # generated index page. |
| object_types = { |
| "arg": domains.ObjType("arg", "arg", "obj"), # macro/function arg |
| "aspect": domains.ObjType("aspect", "aspect", "obj"), |
| "attr": domains.ObjType("attr", "attr", "obj"), # rule attribute |
| "function": domains.ObjType("function", "func", "obj"), |
| "method": domains.ObjType("method", "method", "obj"), |
| "module-extension": domains.ObjType( |
| "module extension", "module_extension", "obj" |
| ), |
| # Providers are close enough to types that we include "type". This |
| # also makes :type: Foo work in directive options. |
| "provider": domains.ObjType("provider", "provider", "type", "obj"), |
| "provider-field": domains.ObjType("provider field", "provider-field", "obj"), |
| "field": domains.ObjType("field", "field", "obj"), |
| "repo-rule": domains.ObjType("repository rule", "repo_rule", "obj"), |
| "rule": domains.ObjType("rule", "rule", "obj"), |
| "tag-class": domains.ObjType("tag class", "tag_class", "obj"), |
| "target": domains.ObjType("target", "target", "obj"), # target in a build file |
| # Flags are also targets, so include "target" for xref'ing |
| "flag": domains.ObjType("flag", "flag", "target", "obj"), |
| # types are objects that have a constructor and methods/attrs |
| "type": domains.ObjType("type", "type", "obj"), |
| "typedef": domains.ObjType("typedef", "typedef", "type", "obj"), |
| } |
| |
| # This controls: |
| # * What is recognized when parsing, e.g. ":bzl:ref:`foo`" requires |
| # "ref" to be in the role dict below. |
| roles = { |
| "arg": roles.XRefRole(), |
| "attr": roles.XRefRole(), |
| "default-value": _DefaultValueRole(), |
| "flag": roles.XRefRole(), |
| "obj": roles.XRefRole(), |
| "required-providers": _RequiredProvidersRole(), |
| "return-type": _ReturnTypeRole(), |
| "rule": roles.XRefRole(), |
| "target": roles.XRefRole(), |
| "type": _TypeRole(), |
| } |
| # NOTE: Directives that have a corresponding object type should use |
| # the same key for both directive and object type. Some directives |
| # look up their corresponding object type. |
| directives = { |
| "aspect": _BzlAspect, |
| "currentfile": _BzlCurrentFile, |
| "function": _BzlFunction, |
| "module-extension": _BzlModuleExtension, |
| "provider": _BzlProvider, |
| "typedef": _BzlTypedef, |
| "provider-field": _BzlProviderField, |
| "field": _BzlField, |
| "repo-rule": _BzlRepositoryRule, |
| "rule": _BzlRule, |
| "tag-class": _BzlTagClass, |
| "target": _BzlTarget, |
| "flag": _BzlFlag, |
| "attr-info": _BzlAttrInfo, |
| } |
| indices = { |
| _BzlIndex, |
| } |
| |
| # NOTE: When adding additional data keys, make sure to update |
| # merge_domaindata |
| initial_data = { |
| # All objects; keyed by full id |
| # dict[str, _ObjectEntry] |
| "objects": {}, |
| # dict[str, dict[str, _ObjectEntry]] |
| "objects_by_type": {}, |
| # Objects within each doc |
| # dict[str, dict[str, _ObjectEntry]] |
| "doc_names": {}, |
| # Objects by a shorter or alternative name |
| # dict[str, dict[str id, _ObjectEntry]] |
| "alt_names": {}, |
| } |
| |
| @override |
| def get_full_qualified_name( |
| self, node: docutils_nodes.Element |
| ) -> typing.Union[str, None]: |
| bzl_file = node.get("bzl:file") |
| symbol_name = node.get("bzl:symbol") |
| ref_target = node.get("reftarget") |
| return ".".join(filter(None, [bzl_file, symbol_name, ref_target])) |
| |
| @override |
| def get_objects(self) -> Iterable[_GetObjectsTuple]: |
| for entry in self.data["objects"].values(): |
| yield entry.to_get_objects_tuple() |
| |
| @override |
| def resolve_any_xref( |
| self, |
| env: environment.BuildEnvironment, |
| fromdocname: str, |
| builder: builders.Builder, |
| target: str, |
| node: addnodes.pending_xref, |
| contnode: docutils_nodes.Element, |
| ) -> list[tuple[str, docutils_nodes.Element]]: |
| del env, node # Unused |
| entry = self._find_entry_for_xref(fromdocname, "obj", target) |
| if not entry: |
| return [] |
| to_docname = entry.index_entry.docname |
| to_anchor = entry.index_entry.anchor |
| ref_node = sphinx_nodes.make_refnode( |
| builder, fromdocname, to_docname, to_anchor, contnode, title=to_anchor |
| ) |
| |
| matches = [(f"bzl:{entry.object_type}", ref_node)] |
| return matches |
| |
| @override |
| def resolve_xref( |
| self, |
| env: environment.BuildEnvironment, |
| fromdocname: str, |
| builder: builders.Builder, |
| typ: str, |
| target: str, |
| node: addnodes.pending_xref, |
| contnode: docutils_nodes.Element, |
| ) -> typing.Union[docutils_nodes.Element, None]: |
| _log_debug( |
| "resolve_xref: fromdocname=%s, typ=%s, target=%s", fromdocname, typ, target |
| ) |
| del env, node # Unused |
| entry = self._find_entry_for_xref(fromdocname, typ, target) |
| if not entry: |
| return None |
| |
| to_docname = entry.index_entry.docname |
| to_anchor = entry.index_entry.anchor |
| return sphinx_nodes.make_refnode( |
| builder, fromdocname, to_docname, to_anchor, contnode, title=to_anchor |
| ) |
| |
| def _find_entry_for_xref( |
| self, fromdocname: str, object_type: str, target: str |
| ) -> typing.Union[_ObjectEntry, None]: |
| if target.startswith("--"): |
| target = target.strip("-") |
| object_type = "flag" |
| |
| # Allow using parentheses, e.g. `foo()` or `foo(x=...)` |
| target, _, _ = target.partition("(") |
| |
| # Elide the value part of --foo=bar flags |
| # Note that the flag value could contain `=` |
| if "=" in target: |
| target = target[: target.find("=")] |
| |
| if target in self.data["doc_names"].get(fromdocname, {}): |
| entry = self.data["doc_names"][fromdocname][target] |
| # Prevent a local doc name masking a global alt name when its of |
| # a different type. e.g. when the macro `foo` refers to the |
| # rule `foo` in another doc. |
| if object_type in self.object_types[entry.object_type].roles: |
| return entry |
| |
| if object_type == "obj": |
| search_space = self.data["objects"] |
| else: |
| search_space = self.data["objects_by_type"].get(object_type, {}) |
| if target in search_space: |
| return search_space[target] |
| |
| _log_debug("find_entry: alt_names=%s", sorted(self.data["alt_names"].keys())) |
| if target in self.data["alt_names"]: |
| # Give preference to shorter object ids. This is a work around |
| # to allow e.g. `FooInfo` to refer to the FooInfo type rather than |
| # the `FooInfo` constructor. |
| entries = sorted( |
| self.data["alt_names"][target].items(), key=lambda item: len(item[0]) |
| ) |
| for _, entry in entries: |
| if object_type in self.object_types[entry.object_type].roles: |
| return entry |
| |
| return None |
| |
| def add_object(self, entry: _ObjectEntry, alt_names=None) -> None: |
| _log_debug( |
| "add_object: full_id=%s, object_type=%s, alt_names=%s", |
| entry.full_id, |
| entry.object_type, |
| alt_names, |
| ) |
| if entry.full_id in self.data["objects"]: |
| existing = self.data["objects"][entry.full_id] |
| raise Exception( |
| f"Object {entry.full_id} already registered: " |
| + f"existing={existing}, incoming={entry}" |
| ) |
| self.data["objects"][entry.full_id] = entry |
| self.data["objects_by_type"].setdefault(entry.object_type, {}) |
| self.data["objects_by_type"][entry.object_type][entry.full_id] = entry |
| |
| repo, label, symbol = _parse_full_id(entry.full_id) |
| if symbol: |
| base_name = symbol.split(".")[-1] |
| else: |
| base_name = label.split(":")[-1] |
| |
| if alt_names is not None: |
| alt_names = list(alt_names) |
| # Add the repo-less version as an alias |
| alt_names.append(label + (f"%{symbol}" if symbol else "")) |
| |
| for alt_name in sorted(set(alt_names)): |
| self.data["alt_names"].setdefault(alt_name, {}) |
| self.data["alt_names"][alt_name][entry.full_id] = entry |
| |
| docname = entry.index_entry.docname |
| self.data["doc_names"].setdefault(docname, {}) |
| self.data["doc_names"][docname][base_name] = entry |
| |
| def merge_domaindata( |
| self, docnames: list[str], otherdata: dict[str, typing.Any] |
| ) -> None: |
| # Merge in simple dict[key, value] data |
| for top_key in ("objects",): |
| self.data[top_key].update(otherdata.get(top_key, {})) |
| |
| # Merge in two-level dict[top_key, dict[sub_key, value]] data |
| for top_key in ("objects_by_type", "doc_names", "alt_names"): |
| existing_top_map = self.data[top_key] |
| for sub_key, sub_values in otherdata.get(top_key, {}).items(): |
| if sub_key not in existing_top_map: |
| existing_top_map[sub_key] = sub_values |
| else: |
| existing_top_map[sub_key].update(sub_values) |
| |
| |
| def _on_missing_reference(app, env: environment.BuildEnvironment, node, contnode): |
| if node["refdomain"] != "bzl": |
| return None |
| if node["reftype"] != "type": |
| return None |
| |
| # There's no Bazel docs for None, so prevent missing xrefs warning |
| if node["reftarget"] == "None": |
| return contnode |
| return None |
| |
| |
| def setup(app): |
| app.add_domain(_BzlDomain) |
| |
| app.add_config_value( |
| "bzl_default_repository_name", |
| default=os.environ.get("SPHINX_BZL_DEFAULT_REPOSITORY_NAME", "@_main"), |
| rebuild="env", |
| types=[str], |
| ) |
| app.connect("missing-reference", _on_missing_reference) |
| |
| # Pygments says it supports starlark, but it doesn't seem to actually |
| # recognize `starlark` as a name. So just manually map it to python. |
| app.add_lexer("starlark", lexer_classes["python"]) |
| app.add_lexer("bzl", lexer_classes["python"]) |
| |
| return { |
| "version": "1.0.0", |
| "parallel_read_safe": True, |
| "parallel_write_safe": True, |
| } |
