Skip to content

Commit

Permalink
Config Doc - Implement a first version of AsciiDoc -> Markdown converter
Browse files Browse the repository at this point in the history 
It is far from being perfect and typically doesn't handle tables. But
it's a good first step.
  • Loading branch information
@gsmet
gsmet committed Sep 13, 2024
1 parent fe7d368 commit 10ffdcb
Show file tree
Hide file tree
Showing 2 changed files with 449 additions and 11 deletions.
296 changes: 285 additions & 11 deletions ...kus/annotation/processor/documentation/config/formatter/JavadocToMarkdownTransformer.java
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
package io.quarkus.annotation.processor.documentation.config.formatter;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import com.github.javaparser.StaticJavaParser;
import com.github.javaparser.javadoc.Javadoc;
Expand All @@ -9,29 +14,59 @@
import com.github.javaparser.javadoc.description.JavadocInlineTag;

import io.quarkus.annotation.processor.documentation.config.model.JavadocFormat;
import io.quarkus.annotation.processor.util.Strings;

public class JavadocToMarkdownTransformer {

private static final Pattern START_OF_LINE = Pattern.compile("^", Pattern.MULTILINE);

private static final Map<String, String> ADMONITIONS = Map.of(
"CAUTION", "🔥",
"IMPORTANT", "❗",
"NOTE", "📌",
"TIP", "💡",
"WARNING", "⚠️");

private static final Pattern HEADER_PATTERN = Pattern.compile("^(=+) (.+)$");
private static final Pattern LIST_ITEM_PATTERN = Pattern.compile("^(\\*+|\\.+) (.+)$");
private static final Pattern IMAGE_BLOCK_PATTERN = Pattern.compile("^image::([^\\s]+)\\[(.*)\\]$");
private static final Pattern IMAGE_INLINE_PATTERN = Pattern.compile("image:([^\\s]+)\\[(.*)\\]");
private static final Pattern ADMONITION_BLOCK_START_PATTERN = Pattern
.compile("^\\[(" + String.join("|", ADMONITIONS.keySet()) + ")\\]$");
private static final String ADMONITION_BLOCK_DELIMITER = "====";
private static final Pattern ADMONITION_INLINE_PATTERN = Pattern
.compile("^(" + String.join("|", ADMONITIONS.keySet()) + "): (.*)$");
private static final Pattern BOLD_PATTERN = Pattern.compile("(?<=^|\\s)\\*(.+?)\\*(?=\\s|$)");
private static final Pattern ITALIC_PATTERN = Pattern.compile("__(.+?)__");
private static final Pattern BLOCK_TITLE_PATTERN = Pattern.compile("^\\.([a-z0-9].*)$");
private static final Pattern SOURCE_BLOCK_START_PATTERN = Pattern.compile("^\\[source(?:,[ ]*([a-z]+))?.*\\]$");
private static final Pattern SOURCE_BLOCK_DELIMITER_PATTERN = Pattern.compile("^(-----*)$");
private static final Pattern QUOTE_BLOCK_START_PATTERN = Pattern.compile("^\\[quote(?:, (.*?))?(?:, (.*?))?]$");
private static final Pattern QUOTE_BLOCK_DELIMITER_PATTERN = Pattern.compile("^(_____*)$");
private static final Pattern LINK_PATTERN = Pattern.compile("(?:link:)([^\\[]+)\\[(.*?)\\]");
private static final Pattern URL_PATTERN = Pattern.compile("\\b(http[^\\[]+)\\[(.*?)\\]");
private static final Pattern XREF_PATTERN = Pattern.compile("xref:([^\\[]+)\\[(.*?)\\]");

public static String toMarkdown(String javadoc, JavadocFormat format) {
if (javadoc == null || javadoc.isBlank()) {
return null;
}

if (format == JavadocFormat.MARKDOWN) {
return javadoc;
} else if (format == JavadocFormat.JAVADOC) {
// the parser expects all the lines to start with "* "
// we add it as it has been previously removed
Javadoc parsedJavadoc = StaticJavaParser.parseJavadoc(START_OF_LINE.matcher(javadoc).replaceAll("* "));
switch (format) {
case MARKDOWN:
return javadoc;
case JAVADOC:
// the parser expects all the lines to start with "* "
// we add it as it has been previously removed
Javadoc parsedJavadoc = StaticJavaParser.parseJavadoc(START_OF_LINE.matcher(javadoc).replaceAll("* "));

// HTML is valid Javadoc but we need to drop the Javadoc tags e.g. {@link ...}
return simplifyJavadoc(parsedJavadoc.getDescription());
// HTML is valid Javadoc but we need to drop the Javadoc tags e.g. {@link ...}
return simplifyJavadoc(parsedJavadoc.getDescription());
case ASCIIDOC:
return asciidocToMarkdown(javadoc);
default:
throw new IllegalArgumentException("Converting from " + format + " to Markdown is not supported");
}

// it's Asciidoc, the fun begins...
return "";
}

/**
Expand Down Expand Up @@ -84,4 +119,243 @@ private static String escapeHtml(String s) {
}
return out.toString();
}

/**
* This obviously don't handle the whole complexity of Asciidoc but should handle most cases.
* <p>
* One thing that might be worth adding is support for titles for source blocks and admonitions but we can add it later on.
* <p>
* It doesn't support tables (yet).
*/
private static String asciidocToMarkdown(String asciidoc) {
List<String> lines = asciidoc.lines().toList();
List<String> result = new ArrayList<>();
String currentAdmonition = null;
boolean inAdmonitionPreamble = false;
boolean inAdmonitionBlock = false;
String currentSourceBlockLanguage = null;
boolean inSourcePreamble = false;
boolean inSourceBlock = false;
String currentSourceBlockTitle = null;
String currentSourceBlockDelimiter = null;
boolean inQuoteBlock = false;
boolean quoteStarted = false;
String currentQuoteBlockDelimiter = null;
String quoteAuthor = null;
String quoteSource = null;

String linePrefix = "";

for (String line : lines) {
String markdownLine = line;

if (inAdmonitionPreamble) {
if (ADMONITION_BLOCK_DELIMITER.equals(line)) {
inAdmonitionBlock = true;
inAdmonitionPreamble = false;
result.add("> [!" + currentAdmonition + "]");
continue;
} else {
// we haven't found a proper delimiter so we ignore the admonition altogether
inAdmonitionPreamble = false;
}
}

if (inAdmonitionBlock) {
if (ADMONITION_BLOCK_DELIMITER.equals(line)) {
inAdmonitionBlock = false;
currentAdmonition = null;
linePrefix = "";
continue;
} else {
linePrefix = "> ";
}
}

if (inSourcePreamble) {
Matcher blockTitleMatcher = BLOCK_TITLE_PATTERN.matcher(line);
if (blockTitleMatcher.matches()) {
currentSourceBlockTitle = blockTitleMatcher.group(1);
}
}

if (inSourceBlock) {
if (currentSourceBlockDelimiter.equals(line)) {
// End of source block
result.add(linePrefix + "```");
inSourcePreamble = false;
inSourceBlock = false;
currentSourceBlockLanguage = null;
currentSourceBlockDelimiter = null;
currentSourceBlockTitle = null;
continue;
} else {
// Inside source block
result.add(linePrefix + markdownLine);
continue;
}
}

Matcher sourceBlockStartMatcher = SOURCE_BLOCK_START_PATTERN.matcher(line);
if (sourceBlockStartMatcher.matches()) {
if (!Strings.isBlank(sourceBlockStartMatcher.group(1))) {
currentSourceBlockLanguage = sourceBlockStartMatcher.group(1).trim();
}
inSourcePreamble = true;
// Skip the start marker
continue;
}

Matcher sourceBlockDelimiterMatcher = SOURCE_BLOCK_DELIMITER_PATTERN.matcher(line);
if (sourceBlockDelimiterMatcher.matches()) {
currentSourceBlockDelimiter = sourceBlockDelimiterMatcher.group(0);
// Start of code block
if (!Strings.isBlank(currentSourceBlockTitle)) {
result.add(linePrefix + "**" + currentSourceBlockTitle + "**");
result.add(linePrefix + "");
}
result.add(
linePrefix + "```" + (!Strings.isBlank(currentSourceBlockLanguage) ? currentSourceBlockLanguage : ""));
inSourcePreamble = false;
inSourceBlock = true;
continue;
}

if (inQuoteBlock) {
Matcher quoteBlockDelimiterMatcher = QUOTE_BLOCK_DELIMITER_PATTERN.matcher(line);
if (!quoteStarted && quoteBlockDelimiterMatcher.matches()) {
currentQuoteBlockDelimiter = quoteBlockDelimiterMatcher.group(0);
continue;
} else if (line.equals(currentQuoteBlockDelimiter)) {
// End of quote block
if (quoteAuthor != null || quoteSource != null) {
result.add(linePrefix + ">");
result.add(linePrefix + "> — " + (quoteAuthor != null ? quoteAuthor : "")
+ (quoteSource != null ? ", " + quoteSource : ""));
}
inQuoteBlock = false;
quoteStarted = false;
currentQuoteBlockDelimiter = null;
continue;
} else {
// Inside quote block
result.add(linePrefix + "> " + line);
quoteStarted = true;
continue;
}
}

Matcher quoteBlockStartMatcher = QUOTE_BLOCK_START_PATTERN.matcher(line);
if (quoteBlockStartMatcher.matches()) {
// Start of quote block
quoteAuthor = quoteBlockStartMatcher.group(1);
quoteSource = quoteBlockStartMatcher.group(2);
inQuoteBlock = true;
continue;
}

Matcher admonitionBlockStartMatcher = ADMONITION_BLOCK_START_PATTERN.matcher(line);
if (admonitionBlockStartMatcher.matches()) {
currentAdmonition = admonitionBlockStartMatcher.group(1);
inAdmonitionPreamble = true;
// Skip the start marker
continue;
}

// Convert headings
Matcher headingMatcher = HEADER_PATTERN.matcher(line);
if (headingMatcher.find()) {
int level = headingMatcher.group(1).length();
String text = headingMatcher.group(2);
markdownLine = "#".repeat(level) + " " + text;
}

// Convert list items
Matcher listItemMatcher = LIST_ITEM_PATTERN.matcher(line);
if (listItemMatcher.find()) {
String marker = listItemMatcher.group(1);
String text = listItemMatcher.group(2);
if (marker.startsWith("*")) {
markdownLine = "- " + text;
} else if (marker.startsWith(".")) {
markdownLine = "1. " + text;
}
}

// Convert italic and bold
markdownLine = convertInline(markdownLine, ITALIC_PATTERN, "*");
markdownLine = convertInline(markdownLine, BOLD_PATTERN, "**");

// Inline Admonitions
if (!inAdmonitionBlock) {
Matcher admonitionInlineMatcher = ADMONITION_INLINE_PATTERN.matcher(line);
if (admonitionInlineMatcher.find()) {
String admonition = admonitionInlineMatcher.group(1);
if (ADMONITIONS.containsKey(admonition)) {
markdownLine = "> " + ADMONITIONS.get(admonition) + " " + admonitionInlineMatcher.group(2);
} else {
markdownLine = "> " + markdownLine;
}
}
}

// Convert block images
Matcher blockImageMatcher = IMAGE_BLOCK_PATTERN.matcher(line);
if (blockImageMatcher.find()) {
String target = blockImageMatcher.group(1);
String altText = blockImageMatcher.group(2);
markdownLine = "![" + altText + "](" + target + ")";
}

// Convert inline images
Matcher inlineImageMatcher = IMAGE_INLINE_PATTERN.matcher(line);
if (inlineImageMatcher.find()) {
String target = inlineImageMatcher.group(1);
String altText = inlineImageMatcher.group(2);
markdownLine = line.replace(inlineImageMatcher.group(), "![" + altText + "](" + target + ")");
}

// Convert links
markdownLine = convertLinksAndXrefs(markdownLine, LINK_PATTERN, "link");
// Convert direct URL links
markdownLine = convertLinksAndXrefs(markdownLine, URL_PATTERN, "url");
// Convert xrefs
markdownLine = convertLinksAndXrefs(markdownLine, XREF_PATTERN, "xref");

result.add(linePrefix + markdownLine);
}

return result.stream().collect(Collectors.joining("\n"));
}

private static String convertInline(String line, Pattern pattern, String markdownDelimiter) {
Matcher matcher = pattern.matcher(line);
StringBuffer sb = new StringBuffer();
while (matcher.find()) {
matcher.appendReplacement(sb, markdownDelimiter + matcher.group(1) + markdownDelimiter);
}
matcher.appendTail(sb);
return sb.toString();
}

private static String convertLinksAndXrefs(String line, Pattern pattern, String type) {
Matcher matcher = pattern.matcher(line);
StringBuffer sb = new StringBuffer();
while (matcher.find()) {
if (type.equals("link") || type.equals("url")) {
matcher.appendReplacement(sb, "[" + matcher.group(2) + "](" + matcher.group(1) + ")");
} else if (type.equals("xref")) {
String xref = matcher.group(1);
if (xref.contains(".adoc")) {
xref = "https://quarkus.io/guides/" + xref.replace(".adoc", "");
} else {
xref = "#" + xref;
}

matcher.appendReplacement(sb, "[" + matcher.group(2) + "](" + xref + ")");
}
}
matcher.appendTail(sb);
return sb.toString();
}
}
Loading

0 comments on commit 10ffdcb

Please sign in to comment.