commit 50f6ce749eb20fc53ace644d3bc91d50829e6c2d
author Richard Levasseur <rlevasseur@google.com> Mon Sep 02 06:14:51 2024 -0700
committer GitHub <noreply@github.com> Mon Sep 02 13:14:51 2024 +0000
tree 3279b9d93fc36347639644655683749cd040a149
parent 36bb556220458d4692cf84c504fa9563b7bebb79

refactor(sphinxdocs): use bazel label format for internal object tracking (#2174)

This changes the way objects are tracked to use Bazel label format
instead of dotted notation.

The dotted notation was problematic because it was ambiguous. For
example, `foo.bar.baz`
could mean `@foo//bar:baz` or `@foo//:bar.bzl%baz`. It also required
various internal hacks
to try and "unparse" the dotted notation into the "meaningful" part of
an object to use
in various contexts. For example, `//foo:bar` usually means `bar` is the
key term to
show, and `//foo:bar.bzl%baz.qux` usually means `qux` or `baz.qux` is
the meaningful part.

Also:
* Make referring to things by the bzl-relative symbol names work. e.g.
`baz.qux` can be
  used to reference `//foo:bar.bzl%baz.qux`
* Fix the name/referencing of runtime_env_toolchains (it was using
singular in the docs)
* Add some more references to bazel inventory
* Omit `--jobs=auto` for `sphinx_run`; multi-job invocations of Sphinx
make it difficult
to interactively run Sphinx for debugging, which is the point of
`sphinx_run`
* Add a basic test of cross-references
* Make xrefs for `--name` format force looking in the flag object type.
This avoids finding
objects of a matching name of another object type; e.g "precompile" is
both a flag and
  attribute name.
* Cleanup the index entries: now the base name is displayed instead of
the full name;
e.g. "foo (target in //bar)" instead of "//foo:bar (target in
//bar:BUILD.bazel)"