(accumulo) branch 3.1 updated: Add a table of contents to MetricsDocGen (#5090)

[domgarguilo]

This is an automated email from the ASF dual-hosted git repository.

domgarguilo pushed a commit to branch 3.1
in repository https://gitbox.apache.org/repos/asf/accumulo.git


The following commit(s) were added to refs/heads/3.1 by this push:
     new 5b2bb6e3e5 Add a table of contents to MetricsDocGen (#5090)
5b2bb6e3e5 is described below

commit 5b2bb6e3e577f2af34b2ed371d9bc63cb901598f
Author: Dom G. <domgargu...@apache.org>
AuthorDate: Thu Nov 21 14:49:41 2024 -0500

    Add a table of contents to MetricsDocGen (#5090)
    
    * these changes will add a table of contents to the metrics documentation 
markdown file that is generated by the build and used in the accumulo website.
---
 .../accumulo/core/metrics/MetricsDocGen.java       | 32 ++++++++++++++++++++--
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git 
a/core/src/main/java/org/apache/accumulo/core/metrics/MetricsDocGen.java 
b/core/src/main/java/org/apache/accumulo/core/metrics/MetricsDocGen.java
index e07bd10748..7fd69bbe5d 100644
--- a/core/src/main/java/org/apache/accumulo/core/metrics/MetricsDocGen.java
+++ b/core/src/main/java/org/apache/accumulo/core/metrics/MetricsDocGen.java
@@ -37,6 +37,7 @@ public class MetricsDocGen {
 
   void generate() {
     pageHeader();
+    generateTableOfContents();
 
     for (var category : Metric.MetricCategory.values()) {
       generateCategorySection(category, category.getSectionTitle());
@@ -54,8 +55,18 @@ public class MetricsDocGen {
     doc.println("Below are the metrics used to monitor various components of 
Accumulo.\n");
   }
 
+  void generateTableOfContents() {
+    doc.println("## Table of Contents\n");
+    for (var category : Metric.MetricCategory.values()) {
+      String sectionId = generateSectionId(category.getSectionTitle());
+      doc.println("- [" + category.getSectionTitle() + "](#" + sectionId + 
")");
+    }
+    doc.println();
+  }
+
   void generateCategorySection(Metric.MetricCategory category, String 
sectionTitle) {
-    beginSection(sectionTitle);
+    String sectionId = generateSectionId(sectionTitle);
+    beginSection(sectionTitle, sectionId);
 
     // Enable block-level HTML parsing
     doc.println("{::options parse_block_html=\"true\" /}");
@@ -70,10 +81,17 @@ public class MetricsDocGen {
     doc.println("{::options parse_block_html=\"false\" /}\n");
   }
 
-  void beginSection(String sectionTitle) {
-    doc.println("\n## " + sectionTitle + "\n");
+  /**
+   * Starts a new section in the documentation. In this case a section is a 
category of metrics.
+   * Adds an anchor to the section title so we can link to it.
+   */
+  void beginSection(String sectionTitle, String sectionId) {
+    doc.println("\n## <a id=\"" + sectionId + "\"></a>" + sectionTitle + "\n");
   }
 
+  /**
+   * Generates a subsection for a metric. This includes the metric name, type, 
and description.
+   */
   void generateMetricSubsection(Metric metric) {
     // Open the div block with markdown enabled
     doc.println("<div markdown=\"1\" class=\"metric-section\">");
@@ -86,6 +104,14 @@ public class MetricsDocGen {
     doc.println("</div>");
   }
 
+  /**
+   * Generates a section ID from a section title. This is used to create 
anchors for linking to
+   * sections.
+   */
+  String generateSectionId(String sectionTitle) {
+    return sectionTitle.toLowerCase().replace(" ", "-").replace(".", "");
+  }
+
   private MetricsDocGen(PrintStream doc) {
     this.doc = doc;
     this.sortedMetrics.addAll(Arrays.asList(Metric.values()));