Add new option categorization and tagging information to HelpCommand'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
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandUtils.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandUtils.java
index 5f57b73..07573fa 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandUtils.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandUtils.java
@@ -21,7 +21,6 @@
import com.google.devtools.build.lib.util.ResourceFileLoader;
import com.google.devtools.common.options.OptionsBase;
import com.google.devtools.common.options.OptionsParser;
-
import java.io.IOException;
import java.util.Collection;
import java.util.Collections;
@@ -114,21 +113,42 @@
* Returns the expansion of the specified help topic.
*
* @param topic the name of the help topic; used in %{command} expansion.
- * @param help the text template of the help message. Certain %{x} variables
- * will be expanded. A prefix of "resource:" means use the .jar
- * resource of that name.
- * @param categoryDescriptions a mapping from option category names to
- * descriptions, passed to {@link OptionsParser#describeOptions}.
- * @param helpVerbosity a tri-state verbosity option selecting between just
- * names, names and syntax, and full description.
+ * @param help the text template of the help message. Certain %{x} variables will be expanded. A
+ * prefix of "resource:" means use the .jar resource of that name.
+ * @param categoryDescriptions a mapping from option category names to descriptions, passed to
+ * {@link OptionsParser#describeOptionsWithDeprecatedCategories}.
+ * @param helpVerbosity a tri-state verbosity option selecting between just names, names and
+ * syntax, and full description.
* @param productName the product name
*/
- public static String expandHelpTopic(String topic, String help,
+ public static final String expandHelpTopic(
+ String topic,
+ String help,
Class<? extends BlazeCommand> commandClass,
Collection<Class<? extends OptionsBase>> options,
Map<String, String> categoryDescriptions,
OptionsParser.HelpVerbosity helpVerbosity,
String productName) {
+ return expandHelpTopic(
+ topic,
+ help,
+ commandClass,
+ options,
+ categoryDescriptions,
+ helpVerbosity,
+ productName,
+ false);
+ }
+
+ public static final String expandHelpTopic(
+ String topic,
+ String help,
+ Class<? extends BlazeCommand> commandClass,
+ Collection<Class<? extends OptionsBase>> options,
+ Map<String, String> categoryDescriptions,
+ OptionsParser.HelpVerbosity helpVerbosity,
+ String productName,
+ boolean useNewCategoryEnum) {
OptionsParser parser = OptionsParser.newOptionsParser(options);
String template;
@@ -137,8 +157,12 @@
try {
template = ResourceFileLoader.loadResource(commandClass, resourceName);
} catch (IOException e) {
- throw new IllegalStateException("failed to load help resource '" + resourceName
- + "' due to I/O error: " + e.getMessage(), e);
+ throw new IllegalStateException(
+ "failed to load help resource '"
+ + resourceName
+ + "' due to I/O error: "
+ + e.getMessage(),
+ e);
}
} else {
template = help;
@@ -148,10 +172,16 @@
throw new IllegalStateException("Help template for '" + topic + "' omits %{options}!");
}
- String optionStr =
- parser
- .describeOptions(categoryDescriptions, helpVerbosity)
- .replace("%{product}", productName);
+ String optionStr;
+ if (useNewCategoryEnum) {
+ optionStr =
+ parser.describeOptions(productName, helpVerbosity).replace("%{product}", productName);
+ } else {
+ optionStr =
+ parser
+ .describeOptionsWithDeprecatedCategories(categoryDescriptions, helpVerbosity)
+ .replace("%{product}", productName);
+ }
return template
.replace("%{product}", productName)
.replace("%{command}", topic)
@@ -166,10 +196,10 @@
/**
* The help page for this command.
*
- * @param categoryDescriptions a mapping from option category names to
- * descriptions, passed to {@link OptionsParser#describeOptions}.
- * @param verbosity a tri-state verbosity option selecting between just names,
- * names and syntax, and full description.
+ * @param categoryDescriptions a mapping from option category names to descriptions, passed to
+ * {@link OptionsParser#describeOptionsWithDeprecatedCategories}.
+ * @param verbosity a tri-state verbosity option selecting between just names, names and syntax,
+ * and full description.
*/
public static String getUsage(
Class<? extends BlazeCommand> commandClass,
@@ -177,7 +207,8 @@
OptionsParser.HelpVerbosity verbosity,
Iterable<BlazeModule> blazeModules,
ConfiguredRuleClassProvider ruleClassProvider,
- String productName) {
+ String productName,
+ boolean useNewCategoryEnum) {
Command commandAnnotation = commandClass.getAnnotation(Command.class);
return BlazeCommandUtils.expandHelpTopic(
commandAnnotation.name(),
@@ -186,6 +217,7 @@
BlazeCommandUtils.getOptions(commandClass, blazeModules, ruleClassProvider),
categoryDescriptions,
verbosity,
- productName);
+ productName,
+ useNewCategoryEnum);
}
}
