Improve generated server properties documentation

* Use gson to pretty-print default values for JSON property types
* Use html tables instead of markdown to support multi-line
  descriptions and default values
* Support markdown syntax in property descriptions by enabling kramdown
  support for mixing markdown and html table cells
* Stop replacing newlines with `<br>` in property descriptions, and just
  accept the property description written in markdown
* Fix documentation for restarting the manager when a
  compaction.coordinator property changes
* Improve PropertyTest and PropertyTypeTest to ensure property
  descriptions and default values restrictions are strictly enforced
* Update Property descriptions to use markdown, and for improved
  readability
* Add more links to other properties and classes in the Property
  descriptions
* Wrap some Property descriptions better, and remove trailing
  backslashes, since they are no longer needed for markdown paragraphs
* Where examples are used for setting properties, show in a style that
  can be used directly in the properties config file, with proper
  escaping
* Standardize using `0` when a zero-value has special meaning for a
  property, so that the value described is shown the same way a user
  would set it (i.e. say `0` instead of "zero", to make it clear that
  the configuration would look like a literal `0`)
* Use class.getName() where possible for class references, and fix
  several classes whose class name was incorrectly hard-coded
* Fix several properties to use PropertyType.CLASSNAME instead of
  PropertyType.STRING when their values are a class name type
* Fix generated document to use the short name of the property type,
  rather than the enum name, which is only in code
* Remove old information about CDATA, since configuration is no longer
  XML-based
* Remove reference to deprecated properties, and update docs to specify
  replacements
* Update PropertyType descriptions to use markdown also

This fixes #5902 and #5903

Author: ctubbsii

core/src/main/java/org/apache/accumulo/core/conf/ConfigurationDocGen.java

@@ -19,133 +19,174 @@
 package org.apache.accumulo.core.conf;
 
 import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.apache.accumulo.core.conf.Property.markdownRef;
 
 import java.io.IOException;
 import java.io.PrintStream;
 import java.util.TreeMap;
 
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonParser;
+
 /**
  * This class generates documentation to inform users of the available configuration properties in a
  * presentable form.
  */
 public class ConfigurationDocGen {
   private final PrintStream doc;
   private final TreeMap<String,Property> sortedProps = new TreeMap<>();
+  private final Gson gsonPrettyPrinter =
+      new GsonBuilder().disableJdkUnsafe().setPrettyPrinting().create();
+
+  private void generate() {
+    doc.print("""
+        ---
+        title: Server Properties (4.x)
+        category: configuration
+        order: 4
+        ---
+
+        <!--
+          WARNING: Do not edit this file. It is a generated file that is copied from Accumulo
+          build (from core/target/generated-docs)
+          -->
+
+        Below are properties set in `accumulo.properties` or the Accumulo shell that configure
+        Accumulo servers (i.e. tablet server, manager, etc). Properties labeled 'Experimental'
+        should not be considered stable and have a higher risk of changing in the future.
+
+        <table>
+          <thead>
+            <tr>
+              <th>Property</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+        <tbody>
+        """);
 
-  void generate() {
-    pageHeader();
-
-    beginTable("Property");
     for (Property prop : sortedProps.values()) {
       if (prop.getType() == PropertyType.PREFIX) {
-        prefixSection(prop);
+        prefixRow(prop);
       } else {
-        property(prop);
+        propertyRow(prop);
       }
     }
 
-    beginSection("Property Types");
-    beginTable("Type");
-    propertyTypeDescriptions();
+    doc.println("""
+          </tbody>
+        </table>
 
-    doc.close();
-  }
+        ### Property Types
 
-  void beginSection(String section) {
-    doc.println("\n### " + section + "\n");
-  }
+        <table>
+          <thead>
+            <tr>
+              <th>Type</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+        <tbody>
+        """);
 
-  void beginTable(String name) {
-    doc.println("| " + name + " | Description |");
-    doc.println("|--------------|-------------|");
-  }
+    for (PropertyType type : PropertyType.values()) {
+      if (type != PropertyType.PREFIX) {
+        doc.printf("""
+            <tr>
+            <td>%s</td>
+            <td markdown="1">
 
-  void pageHeader() {
-    doc.println("---");
-    doc.println("title: Server Properties (4.x)");
-    doc.println("category: configuration");
-    doc.println("order: 4");
-    doc.println("---\n");
-    doc.println("<!-- WARNING: Do not edit this file. It is a generated file"
-        + " that is copied from Accumulo build (from core/target/generated-docs) -->\n");
-    doc.println("Below are properties set in `accumulo.properties` or the"
-        + " Accumulo shell that configure Accumulo servers (i.e. tablet server,"
-        + " manager, etc). Properties labeled 'Experimental' should not be considered stable"
-        + " and have a higher risk of changing in the future.\n");
-  }
+            %s
 
-  void prefixSection(Property prefix) {
-    boolean depr = prefix.isDeprecated();
-    String key = strike("<a name=\"" + prefix.getKey().replace(".", "_")
-        + "prefix\" class=\"prop\"></a> **" + prefix.getKey() + "***", depr);
-    String description = prefix.isExperimental() ? "**Experimental**<br>" : "";
-    description += "**Available since:** " + prefix.availableSince() + "<br>";
-    if (depr) {
-      description += "*Deprecated since:* " + prefix.deprecatedSince() + "<br>";
-      if (prefix.isReplaced()) {
-        description += "*Replaced by:* <a href=\"#" + prefix.replacedBy().getKey().replace(".", "_")
-            + "prefix\">" + prefix.replacedBy() + "</a><br>";
+            </td>
+            </tr>
+            """, type.toString(), type.getFormatDescription());
       }
     }
-    description += strike(sanitize(prefix.getDescription()), depr);
-    doc.println("| " + key + " | " + description + " |");
+
+    doc.println("""
+          </tbody>
+        </table>
+        """);
+
+    doc.close();
+  }
+
+  private void prefixRow(Property prefix) {
+    boolean depr = prefix.isDeprecated();
+    doc.printf("""
+        <tr>
+        <td markdown="1"><a name="%sprefix" class="prop"></a>
+        %s**%s\\***%s
+        </td>
+        <td markdown="1" style="max-width: 600px">
+        %s
+        **Available since:** %s<br>
+        %s%s
+
+        %s
+
+        </td>
+        </tr>
+        """, prefix.getKey().replace(".", "_"), depr ? "~~" : "", prefix.getKey(), depr ? "~~" : "",
+        prefix.isExperimental() ? "**&#9888;Experimental&#9888;**<br>" : "",
+        prefix.availableSince(),
+        depr ? "*Deprecated since:* " + prefix.deprecatedSince() + "<br>" : "",
+        depr && prefix.isReplaced()
+            ? "*Replaced by:* %s<br>".formatted(markdownRef(prefix.replacedBy().getKey())) : "",
+        prefix.getDescription());
   }
 
-  void property(Property prop) {
+  private void propertyRow(Property prop) {
     boolean depr = prop.isDeprecated();
-    String key = strike(
-        "<a name=\"" + prop.getKey().replace(".", "_") + "\" class=\"prop\"></a> " + prop.getKey(),
-        depr);
-    String description = prop.isExperimental() ? "**Experimental**<br>" : "";
-    description += "**Available since:** ";
-    if (prop.getKey().startsWith("manager.")
-        && (prop.availableSince().startsWith("1.") || prop.availableSince().startsWith("2.0"))) {
-      description += "2.1.0 (formerly *master." + prop.getKey().substring(8) + "* since "
-          + prop.availableSince() + ")<br>";
-    } else {
-      description += prop.availableSince() + "<br>";
-    }
-    if (depr) {
-      description += "*Deprecated since:* " + prop.deprecatedSince() + "<br>";
-      if (prop.isReplaced()) {
-        description += "*Replaced by:* <a href=\"#" + prop.replacedBy().getKey().replace(".", "_")
-            + "\">" + prop.replacedBy() + "</a><br>";
-      }
-    }
-    description += strike(sanitize(prop.getDescription()), depr) + "<br>"
-        + strike("**type:** " + prop.getType().name(), depr) + ", "
-        + strike("**zk mutable:** " + isZooKeeperMutable(prop), depr) + ", ";
-    String defaultValue = sanitize(prop.getDefaultValue()).trim();
+    String del = depr ? "~~" : "";
+    String availableSince = prop.getKey().startsWith("manager.")
+        && (prop.availableSince().startsWith("1.") || prop.availableSince().startsWith("2.0"))
+            ? "2.1.0 (formerly *master." + prop.getKey().substring(8) + "* since "
+                + prop.availableSince() + ")"
+            : prop.availableSince();
+    String defaultValue = prop.getDefaultValue();
     if (defaultValue.isEmpty()) {
-      description += strike("**default value:** empty", depr);
-    } else if (defaultValue.contains("\n")) {
-      // deal with multi-line values, skip strikethrough of value
-      description += strike("**default value:** ", depr) + "\n```\n" + defaultValue + "\n```\n";
+      defaultValue = "empty";
     } else if (prop.getType() == PropertyType.CLASSNAME
         && defaultValue.startsWith("org.apache.accumulo")) {
-      description += strike("**default value:** {% jlink -f " + defaultValue + " %}", depr);
+      defaultValue = "{% jlink -f " + defaultValue + " %}";
     } else {
-      description += strike("**default value:** `" + defaultValue + "`", depr);
-    }
-    doc.println("| " + key + " | " + description + " |");
-  }
-
-  private String strike(String s, boolean isDeprecated) {
-    return (isDeprecated ? "~~" : "") + s + (isDeprecated ? "~~" : "");
-  }
-
-  void propertyTypeDescriptions() {
-    for (PropertyType type : PropertyType.values()) {
-      if (type == PropertyType.PREFIX) {
-        continue;
-      }
-      doc.println(
-          "| " + sanitize(type.toString()) + " | " + sanitize(type.getFormatDescription()) + " |");
+      defaultValue = switch (prop.getType()) {
+        case JSON, FATE_META_CONFIG, FATE_USER_CONFIG -> """
+            `%s`
+
+            Formatted JSON (for convenience only):
+            ```json
+            %s
+            ```
+            """.formatted(defaultValue,
+            gsonPrettyPrinter.toJson(JsonParser.parseString(defaultValue)));
+        default -> "`%s`".formatted(defaultValue);
+      };
     }
-  }
-
-  String sanitize(String str) {
-    return str.replace("\n", "<br>");
+    doc.printf("""
+        <tr>
+        <td markdown="1"><a name="%s" class="prop"></a>
+        %s%s%s
+        </td>
+        <td markdown="1" style="max-width: 600px">
+        %s
+        **Available since:** %s<br>
+        %s%s
+
+        %s
+
+        **type:** %s, **zk mutable:** %s, **default value:** %s
+        </td>
+        </tr>
+        """, prop.getKey().replace(".", "_"), del, prop.getKey(), del,
+        prop.isExperimental() ? "**&#9888;Experimental&#9888;**<br>" : "", availableSince,
+        depr ? "*Deprecated since:* " + prop.deprecatedSince() + "<br>" : "",
+        depr && prop.isReplaced()
+            ? "*Replaced by:* %s<br>".formatted(markdownRef(prop.replacedBy().getKey())) : "",
+        prop.getDescription(), prop.getType().toString(), isZooKeeperMutable(prop), defaultValue);
   }
 
   private ConfigurationDocGen(PrintStream doc) {
@@ -160,7 +201,9 @@ private String isZooKeeperMutable(Property prop) {
       return "no";
     }
     if (Property.isFixedZooPropertyKey(prop)) {
-      return "yes but requires restart of the " + prop.getKey().split("[.]")[0];
+      String serverName = prop.getKey().startsWith("compaction.coordinator.") ? "manager"
+          : prop.getKey().split("[.]")[0];
+      return "yes, but requires restart of the " + serverName;
     }
     return "yes";
   }