Site: show top-level option next to flags on command line reference

[jschaf]

Page link:

https://bazel.build/reference/command-line-reference

Problem description (include actual vs expected text, if applicable):

When navigating to an anchor link, figuring out which top-level option (common, build, query, etc.) the flag belongs to is difficult. For example, when navigating to https://docs.bazel.build/versions/main/command-line-reference.html#flag--experimental_remote_build_event_upload, the only way to figure out the top-level option is to scroll up. Since the page is massive, it's easy to miss the top-level option.

The top-level option is important because I need to know it to update .bazelrc. For example, buildbuddy-io/buildbuddy#3731

Where do you see this issue? (include link to specific section of the page, if applicable)

https://docs.bazel.build/versions/main/command-line-reference.html#flag--experimental_remote_build_event_upload

Any other information you'd like to share?

Some common patterns for improving positioning information for large pages like this:

1. Show the top-level option as a fixed header to the left when scrolling.
2. Show the top-level option on every flag.
3. Highlight the top-level option when scrolling.

[ian-h-chamberlain]

See also #3758 which proposes a different solution (but I think would solve the same problem, showing what command(s) a flag goes with).

This typically causes me a lot of trial-and-error when plumbing in a flag to .bazelrc since I often don't know if I should use common, build, etc.

Regarding the scrolling — there is sort of already a UI for this in the sidebar table of contents, which already has highlighting.

However, the highlighting is never updated unless clicking the sidebar (from what I can tell). So maybe it would help if just clicking anchors forced a refresh of the current section on the sidebar or something like that.

[fmeum]

This typically causes me a lot of trial-and-error when plumbing in a flag to .bazelrc since I often don't know if I should use common, build, etc.

@ian-h-chamberlain With 6.3.0 you can always use either common or startup (except for Starlark-defined flags, which require 6.4.0).