command-line-reference options should be grouped by DocumentationCategory, not command #3758
Assignees
Labels
not stale
Issues or PRs that are inactive but not considered stale
P3
We're not considering working on this, but happy to review a PR. (No assignee)
team-Documentation
Documentation improvements that cannot be directly linked to other team labels
team-OSS
Issues for the Bazel OSS team: installation, release processBazel packaging, website
type: documentation (cleanup)
type: feature request
Comments
|
fyi @michelleirvine @spomorski, filed this after discussing the generated option docs with Michelle. |
bazel-io
pushed a commit
that referenced
this issue
Sep 27, 2017
…s output. If setting flag --use_new_category_enum, group the options by the new categories in both the command line output and the "everything-as-html" output used for the generated docs at https://bazel.build/versions/master/docs/command-line-reference.html. In the html output, the effect and metadata tags are listed for each option, with links to their descriptions at the bottom of the page. The tags only appear in the terminal output in -l/--long/--help_verbosity=long, and only the names appear. This is still experimental as the majority of options do not yet use the new categorization system. The new output can be seen in command-line-reference.html format by adding the new flag to the "help everything-as-html" line in //src/main/java/com/google/devtools/build/lib:gen_command-line-reference. The html output is in the same order as before (by blaze rule, with inherited options not repeated), which means it still has duplicate options, that should ideally be fixed separately. I propose either dropping the high-level grouping and just grouping the options by documentation category, or potentially grouping them by optionsbase in some non-class-naming way, and listing the commands that they apply to, as more and more optionsbases are used by multiple commands without being inherited (for example, all BuildEventServiceOptions are listed 20 times). People probably use ctrl-f to navigate this page anyway. Once we know that we only list each option once, we can actually have links to the options, which will make it possible to have links in the expansion lists. Issue #3758 RELNOTES: added experimental --use_new_category_enum to the help command to output options grouped by the new type of category. PiperOrigin-RevId: 170116553
bazel-io
pushed a commit
that referenced
this issue
Jan 22, 2018
Bazel help output will now use the new categories by default, including for the generated html documentation at https://bazel.build/versions/master/docs/command-line-reference.html Issue #3758 - this switches to the new categories, but the grouping is still by command, which leads to duplicate options RELNOTES: None PiperOrigin-RevId: 182815006
jin
added
team-OSS
philwo
added
the
P3
ShreeM01
added
the
team-Documentation
|
Thank you for contributing to the Bazel repository! This issue has been marked as stale since it has not had any activity in the last 1+ years. It will be closed in the next 90 days unless any other activity occurs. If you think this issue is still relevant and should stay open, please post any comment here and the issue will no longer be marked as stale. |
github-actions
bot
added
the
stale
brentleyjones
added
not stale
|
I am doing a series of cleanups that help with the underlying issue, but still keep them grouped by command (I consider this more useful). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The current generated option documentation groups options by command. For options that are inherited through the command hierarchy (
testinherits frombuild, etc), we don't list the options twice, but for options lists that are included in many commands explicitely, we list the option multiple times.Instead of this cat and mouse game where, to find out if an option applies to a command, you see what command it's listed under and what other commands inherit from it, the options should just list the commands to which they apply:
At this point, each option would only need to be listed once, which means we could link to the option documentation clearly from elsewhere in the docs.
The text was updated successfully, but these errors were encountered: