commit bcad22120cfa63cf60368eaabc5dfa4e0eaef9fe
author Jingwen Chen <jingwen@google.com> Tue Dec 18 14:56:55 2018 -0800
committer Copybara-Service <copybara-piper@google.com> Tue Dec 18 14:58:44 2018 -0800
tree fc3585bfd6e18dbe0b7037712a2d71e956a7ff1e
parent 7d174b2bca3b5329786b56dcc609bccebbaeea23

Linkify all flags in the Command Line Reference

This updates the option html emitter to add anchor links and id tags to
each generated flag in the command line reference. It also fixes its
color to be consistently red in the code block, instead of the standard
Bazel green for links.

Live demo:

https://bazel-docs-staging.netlify.com/versions/master/command-line-reference.html#flag--all_incompatible_changes
https://bazel-docs-staging.netlify.com/versions/master/command-line-reference.html#flag--experimental_oom_more_eagerly_threshold

When not hovering:

![ss](https://user-images.githubusercontent.com/347918/50126797-6b1f0880-023c-11e9-85fa-5d47c7f62a25.png)

When hovering:

![ss](https://user-images.githubusercontent.com/347918/50126805-740fda00-023c-11e9-93c2-d69e719dcf34.png)

and that generates the link:

`https://docs.bazel.build/versions/<version>/command-line-reference.html#flag--experimental_oom_more_eagerly_threshold`

Expanded flags are also linkified:

![ss](https://user-images.githubusercontent.com/347918/50127567-b2f35f00-023f-11e9-8bf4-e39d3937929c.png)

There may be a concern that we don't guarantee that flags are only generated once, and can be duplicated, but because flag definitions don't change, linking to the first instance of the flag is safe.

Fixes https://github.com/bazelbuild/bazel/issues/3502

Change-Id: I6775feaa48558029b943b3206891e8b6860bb5d9
RELNOTES: None.

Closes #6954.

Change-Id: I37057365b0a117e269bdaa56bdec8153fe0a5b85
PiperOrigin-RevId: 226065220

src/main/java/com/google/devtools/common/options/OptionsUsage.java

diff --git a/src/main/java/com/google/devtools/common/options/OptionsUsage.java b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
index 6dee0eb..543b7a8 100644
--- a/src/main/java/com/google/devtools/common/options/OptionsUsage.java
+++ b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
@@ -18,6 +18,7 @@
 import com.google.common.base.Splitter;
 import com.google.common.base.Strings;
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Iterables;
 import com.google.common.escape.Escaper;
 import java.text.BreakIterator;
 import java.util.ArrayList;
@@ -200,8 +201,25 @@
     String flagName = getFlagName(optionDefinition);
     String valueDescription = optionDefinition.getValueTypeHelpText();
     String typeDescription = getTypeDescription(optionDefinition);
-    usage.append("<dt><code><a name=\"flag--").append(plainFlagName).append("\"></a>--");
-    usage.append(flagName);
+
+    // String.format is a lot slower, sometimes up to 10x.
+    // https://stackoverflow.com/questions/925423/is-it-better-practice-to-use-string-format-over-string-concatenation-in-java
+    //
+    // Considering that this runs for every flag in the CLI reference, it's better to use regular
+    // appends here.
+    usage
+        // Add the id of the flag to point anchor hrefs to it
+        .append("<dt id=\"flag--")
+        .append(plainFlagName)
+        .append("\">")
+        // Add the href to the id hash
+        .append("<code><a href=\"#flag--")
+        .append(plainFlagName)
+        .append("\">")
+        .append("--")
+        .append(flagName)
+        .append("</a>");
+
     if (optionDefinition.usesBooleanValueSyntax() || optionDefinition.isVoidField()) {
       // Nothing for boolean, tristate, boolean_or_enum, or void options.
     } else if (!valueDescription.isEmpty()) {
@@ -249,14 +267,21 @@
         Preconditions.checkArgument(!expansion.isEmpty());
         expandsMsg = new StringBuilder("Expands to:<br/>\n");
         for (String exp : expansion) {
-          // TODO(ulfjack): We should link to the expanded flags, but unfortunately we don't
+          // TODO(jingwen): We link to the expanded flags here, but unfortunately we don't
           // currently guarantee that all flags are only printed once. A flag in an OptionBase that
           // is included by 2 different commands, but not inherited through a parent command, will
-          // be printed multiple times.
+          // be printed multiple times. Clicking on the flag will bring the user to its first
+          // definition.
           expandsMsg
-              .append("&nbsp;&nbsp;<code>")
+              .append("&nbsp;&nbsp;")
+              .append("<code><a href=\"#flag")
+              // Link to the '#flag--flag_name' hash.
+              // Some expansions are in the form of '--flag_name=value', so we drop everything from
+              // '=' onwards.
+              .append(Iterables.get(Splitter.on('=').split(escaper.escape(exp)), 0))
+              .append("\">")
               .append(escaper.escape(exp))
-              .append("</code><br/>\n");
+              .append("</a></code><br/>\n");
         }
       }
       usage.append(expandsMsg.toString());