add support for rendering HTML in markdown table cells

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>");

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);
+ }
 }