Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Sep 2, 2024

Conversation

rickeylev
Copy link
Contributor

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)"

@rickeylev rickeylev force-pushed the sphinxdocs.refactor.objid branch 2 times, most recently from 246fef1 to f949721 Compare September 2, 2024 00:57
@aignas aignas added this pull request to the merge queue Sep 2, 2024
Merged via the queue into bazelbuild:main with commit 50f6ce7 Sep 2, 2024
4 checks passed
@rickeylev rickeylev deleted the sphinxdocs.refactor.objid branch September 3, 2024 03:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants