search

bazelbuild / bazel

a fast, scalable, multi-language and extensible build system
https://bazel.build
Apache License 2.0
22.99k stars 4.03k forks source link

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

Open jschaf opened 1 year ago

jschaf commented 1 year ago

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, https://github.com/buildbuddy-io/buildbuddy/issues/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 commented 11 months ago

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.

Screenshot 2023-10-04 at 08 57 47

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 commented 11 months ago

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