From ccd1637523a4c9193747a34084ae0a5631ebc6ac Mon Sep 17 00:00:00 2001
From: Chai Varier <cvarier@bostondynamics.com>
Date: Wed, 3 Nov 2021 15:13:01 -0400
Subject: [PATCH] add support for rendering HTML in markdown table cells

---
 .../build/skydoc/rendering/MarkdownUtil.java  | 44 +++++++++++++++----
 .../devtools/build/skydoc/SkydocTest.java     | 41 +++++++++++++++++
 2 files changed, 76 insertions(+), 9 deletions(-)

diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java b/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
index 331c80db798042..d2040546376ef9 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
@@ -35,21 +35,47 @@ public final class MarkdownUtil {
   private static final int MAX_LINE_LENGTH = 100;
 
   /**
-   * Return a string that formats the input string so it is displayable in a markdown table cell.
-   * This performs the following operations:
+   * Wrapper around {@link #markdownCellFormatWithRenderedHtml}, calling it with HTML rendering disabled.
    *
+   * @return The formatted string, upon which the following operations have been performed:
    * <ul>
-   *   <li>Trims the string of leading/trailing whitespace.
-   *   <li>Transforms the string using {@link #htmlEscape}.
-   *   <li>Transforms multline code (```) tags into preformatted code HTML tags.
-   *   <li>Transforms single-tick code (`) tags into code HTML tags.
-   *   <li>Transforms 'new paraphgraph' patterns (two or more sequential newline characters) into
+   *   <li>Trim the string of leading/trailing whitespace.
+   *   <li>Transform the string using {@link #htmlEscape}.
+   *   <li>Transform multline code (```) tags into preformatted code HTML tags.
+   *   <li>Transform single-tick code (`) tags into code HTML tags.
+   *   <li>Transform 'new paraphgraph' patterns (two or more sequential newline characters) into
    *       line break HTML tags.
-   *   <li>Turns lingering new line tags into spaces (as they generally indicate intended line wrap.
+   *   <li>Turn lingering new line tags into spaces (as they generally indicate intended line wrap.
    * </ul>
    */
   public String markdownCellFormat(String docString) {
-    String resultString = htmlEscape(docString.trim());
+    return markdownCellFormatWithRenderedHtml(docString, false);
+  }
+
+  /**
+   * Return a string that formats the input string, possibly containing HTML, so it is displayable in a 
+   * markdown table cell.
+   * 
+   * @param docString The input string
+   * @param renderHtml If set to true, rendering HTML in markdown table cells will be enabled.
+   *                   Otherwise, the string will be transformed using {@link #htmlEscape}.
+   *
+   * @return The formatted string, upon which the following operations have been performed:
+   * <ul>
+   *   <li>Trim the string of leading/trailing whitespace.
+   *   <li>If <code>renderHtml</code> is false, transform the string using {@link #htmlEscape}.
+   *   <li>Transform multline code (```) tags into preformatted code HTML tags.
+   *   <li>Transform single-tick code (`) tags into code HTML tags.
+   *   <li>Transform 'new paraphgraph' patterns (two or more sequential newline characters) into
+   *       line break HTML tags.
+   *   <li>Turn lingering new line tags into spaces (as they generally indicate intended line wrap.
+   * </ul>
+   */
+  public String markdownCellFormatWithRenderedHtml(String docString, Boolean renderHtml) {
+    String resultString = docString.trim();
+    if (!renderHtml) {
+      resultString = htmlEscape(resultString);
+    }
 
     resultString = replaceWithTag(resultString, "```", "<pre><code>", "</code></pre>");
     resultString = replaceWithTag(resultString, "`", "<code>", "</code>");
diff --git a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
index d5f849e0d9e0de..22179f981f0adf 100644
--- a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
+++ b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
@@ -30,6 +30,7 @@
 import com.google.devtools.build.skydoc.rendering.DocstringParseException;
 import com.google.devtools.build.skydoc.rendering.FunctionUtil;
 import com.google.devtools.build.skydoc.rendering.ProtoRenderer;
+import com.google.devtools.build.skydoc.rendering.MarkdownUtil;
 import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AspectInfo;
 import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AttributeType;
 import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ModuleInfo;
@@ -53,6 +54,7 @@
 public final class SkydocTest extends BuildViewTestCase {
 
   private SkydocMain skydocMain;
+  private MarkdownUtil util;
 
   @Before
   public void setUp() throws IOException {
@@ -83,6 +85,7 @@ public boolean fileExists(String pathString) {
             },
             "io_bazel",
             ImmutableList.of("/other_root", "."));
+    util = new MarkdownUtil();
   }
 
   @Test
@@ -829,4 +832,42 @@ public void testModuleDocAcrossFiles() throws Exception {
     String moduleDoc = moduleInfo.getModuleDocstring();
     assertThat(moduleDoc).isEqualTo("Should be displayed.");
   }
+
+  @Test
+  public void testMarkdownCellFormat() throws Exception {
+    // Exercises all the operations of markdownCellFormat()
+    String testData = " test_start <a></a>:\n"
+                        + " Test<br>\n"
+                        + " `test`\n"
+                        + " ``` \n"
+                        + " test\n"
+                        + " ```\n\n"
+                        + " test\n    \n"
+                        + " test_end ";
+
+    String expected = "test_start &lt;a&gt;&lt;/a&gt;:  "
+                        + "Test&lt;br&gt;  <code>test</code>  <pre><code>   "
+                        + "test  </code></pre><br><br> test<br><br> test_end";
+
+    assertThat(util.markdownCellFormat(testData)).isEqualTo(expected);
+  }
+
+  @Test
+  public void testMarkdownCellFormatWithRenderedHtml() throws Exception {
+    // Exercises markdownCellFormatWithRenderedHtml() with renderHtml set to true
+    String testData = " test_start <a></a>:\n"
+                        + " Test<br>\n"
+                        + " `test`\n"
+                        + " ``` \n"
+                        + " test\n"
+                        + " ```\n\n"
+                        + " test\n    \n"
+                        + " test_end ";
+
+    String expected = "test_start <a></a>:  "
+                        + "Test<br>  <code>test</code>  <pre><code>   "
+                        + "test  </code></pre><br><br> test<br><br> test_end";
+
+    assertThat(util.markdownCellFormatWithRenderedHtml(testData, true)).isEqualTo(expected);
+  }
 }