Add support for description lists in parser-doxia-module (#772)

* Tested all examples from official docs
* Update maven-plugin docs

Closes #751

asciidoctor-parser-doxia-module/src/it/maven-site-plugin/src/site/asciidoc/sample.adoc

@@ -75,3 +75,16 @@ public class HelloWorld {
 . Protons
 . Electrons
 . Neutrons
+
+==== Description list
+
+Operating Systems::
+Linux:::
+. Fedora
+* Desktop
+. Ubuntu
+* Desktop
+* Server
+BSD:::
+. FreeBSD
+. NetBSD

asciidoctor-parser-doxia-module/src/it/maven-site-plugin/validate.groovy

@@ -42,6 +42,15 @@ new HtmlAsserter(htmlContent).with { asserter ->
     asserter.containsSectionTitle("Ordered list", 4)
     asserter.containsOrderedList("Protons", "Electrons", "Neutrons")
 
+    asserter.containsSectionTitle("Description list", 4)
+    asserter.descriptionListTerm("Operating Systems")
+    asserter.descriptionListTerm("Linux")
+    asserter.contains("<li>Fedora")
+    asserter.containsUnorderedList("Desktop")
+    asserter.contains("<li>Ubuntu")
+    asserter.containsUnorderedList("Desktop", "Server")
+    asserter.descriptionListTerm("BSD")
+    asserter.containsOrderedList("FreeBSD", "NetBSD")
 }
 
 String strong(String text) {
@@ -111,6 +120,11 @@ class HtmlAsserter {
         return content.indexOf(value, lastAssertionCursor)
     }
 
+    void contains(String text) {
+        def found = find(text)
+        assertFound("HTML text", text, found)
+    }
+
     void containsDocumentTitle(String value) {
         def found = find("<h1>$value</h1>")
         assertFound("Document Title", value, found)
@@ -160,6 +174,11 @@ class HtmlAsserter {
         assertFound("Ordered list", values.join(','), found)
     }
 
+    void descriptionListTerm(String term) {
+        def found = find("<dt>${term}</dt>")
+        assertFound("Description list", term, found)
+    }
+
     void containsTable(int columns, int rows, List<String> headers, String caption) {
         def start = content.indexOf("<table", lastAssertionCursor)
         def end = content.indexOf("</table>", lastAssertionCursor) + "</table>".length()

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/NodesSinker.java

@@ -6,6 +6,7 @@
 
 import org.apache.maven.doxia.sink.Sink;
 import org.asciidoctor.ast.StructuralNode;
+import org.asciidoctor.maven.site.ast.processors.DescriptionListNodeProcessor;
 import org.asciidoctor.maven.site.ast.processors.DocumentNodeProcessor;
 import org.asciidoctor.maven.site.ast.processors.ImageNodeProcessor;
 import org.asciidoctor.maven.site.ast.processors.ListItemNodeProcessor;
@@ -39,23 +40,26 @@ public NodesSinker(Sink sink) {
 
         UnorderedListNodeProcessor unorderedListNodeProcessor = new UnorderedListNodeProcessor(sink);
         OrderedListNodeProcessor orderedListNodeProcessor = new OrderedListNodeProcessor(sink);
+        DescriptionListNodeProcessor descriptionListNodeProcessor = new DescriptionListNodeProcessor(sink);
 
         ListItemNodeProcessor listItemNodeProcessor = new ListItemNodeProcessor(sink);
-        listItemNodeProcessor.setNodeProcessors(Arrays.asList(unorderedListNodeProcessor, orderedListNodeProcessor));
+        listItemNodeProcessor.setNodeProcessors(Arrays.asList(unorderedListNodeProcessor, orderedListNodeProcessor, descriptionListNodeProcessor));
         unorderedListNodeProcessor.setItemNodeProcessor(listItemNodeProcessor);
         orderedListNodeProcessor.setItemNodeProcessor(listItemNodeProcessor);
+        descriptionListNodeProcessor.setItemNodeProcessor(listItemNodeProcessor);
 
         nodeProcessors = Arrays.asList(
-                new DocumentNodeProcessor(sink),
-                new ImageNodeProcessor(sink),
-                new ListingNodeProcessor(sink),
-                new LiteralNodeProcessor(sink),
-                new ParagraphNodeProcessor(sink),
-                new PreambleNodeProcessor(sink),
-                new SectionNodeProcessor(sink),
-                new TableNodeProcessor(sink),
-                orderedListNodeProcessor,
-                unorderedListNodeProcessor
+            new DocumentNodeProcessor(sink),
+            new ImageNodeProcessor(sink),
+            new ListingNodeProcessor(sink),
+            new LiteralNodeProcessor(sink),
+            new ParagraphNodeProcessor(sink),
+            new PreambleNodeProcessor(sink),
+            new SectionNodeProcessor(sink),
+            new TableNodeProcessor(sink),
+            descriptionListNodeProcessor,
+            orderedListNodeProcessor,
+            unorderedListNodeProcessor
         );
     }
 
@@ -72,8 +76,8 @@ private void processNode(StructuralNode node, int depth) {
         try {
             // Only one matches in current NodeProcessors implementation
             Optional<NodeProcessor> nodeProcessor = nodeProcessors.stream()
-                    .filter(np -> np.applies(node))
-                    .findFirst();
+                .filter(np -> np.applies(node))
+                .findFirst();
             if (nodeProcessor.isPresent()) {
                 NodeProcessor processor = nodeProcessor.get();
                 processor.process(node);
@@ -90,6 +94,6 @@ private void processNode(StructuralNode node, int depth) {
 
     private void traverse(StructuralNode node, int depth) {
         node.getBlocks()
-                .forEach(b -> processNode(b, depth + 1));
+            .forEach(b -> processNode(b, depth + 1));
     }
 }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/DescriptionListNodeProcessor.java

@@ -0,0 +1,77 @@
+package org.asciidoctor.maven.site.ast.processors;
+
+import java.util.List;
+
+import org.apache.maven.doxia.sink.Sink;
+import org.asciidoctor.ast.DescriptionList;
+import org.asciidoctor.ast.DescriptionListEntry;
+import org.asciidoctor.ast.ListItem;
+import org.asciidoctor.ast.StructuralNode;
+import org.asciidoctor.maven.site.ast.NodeProcessor;
+
+/**
+ * Description list processor.
+ *
+ * @author abelsromero
+ * @since 3.0.0
+ */
+public class DescriptionListNodeProcessor extends AbstractSinkNodeProcessor implements NodeProcessor {
+
+    private ListItemNodeProcessor itemNodeProcessor;
+
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
+    public DescriptionListNodeProcessor(Sink sink) {
+        super(sink);
+    }
+
+    /**
+     * Inject a {@link ListItemNodeProcessor}.
+     *
+     * @param nodeProcessor {@link ListItemNodeProcessor}
+     */
+    public void setItemNodeProcessor(ListItemNodeProcessor nodeProcessor) {
+        this.itemNodeProcessor = nodeProcessor;
+    }
+
+    @Override
+    public boolean applies(StructuralNode node) {
+        return "dlist".equals(node.getNodeName());
+    }
+
+    @Override
+    public boolean isTerminal(StructuralNode node) {
+        return true;
+    }
+
+    @Override
+    public void process(StructuralNode node) {
+
+        final List<DescriptionListEntry> items = ((DescriptionList) node).getItems();
+        final Sink sink = getSink();
+
+        if (!items.isEmpty()) {
+            sink.definitionList();
+            for (DescriptionListEntry item : items) {
+                // About the model, see https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/.E2.9C.94.20Description.20List.20AST.20structure/near/419353063
+                final ListItem term = item.getTerms().get(0);
+                sink.definedTerm();
+                sink.rawText(term.getText());
+                sink.definedTerm_();
+
+                final ListItem description = item.getDescription();
+                sink.definition();
+                if (description.getBlocks().isEmpty()) {
+                    sink.rawText(description.getText());
+                } else {
+                    itemNodeProcessor.process(description);
+                }
+                sink.definition_();
+            }
+            sink.definitionList_();
+        }
+    }
+}

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/ListItemNodeProcessor.java

@@ -45,12 +45,19 @@ public boolean applies(StructuralNode node) {
     public void process(StructuralNode node) {
         final ListItem item = (ListItem) node;
         final Sink sink = getSink();
-        if (isUnorderedListItem(item))
-            sink.listItem();
-        else
-            sink.numberedListItem();
+        final ListType listType = getListType(item);
 
-        String text = item.getText();
+        // description type does not require any action
+        switch (listType) {
+            case ordered:
+                sink.numberedListItem();
+                break;
+            case unordered:
+                sink.listItem();
+                break;
+        }
+
+        final String text = item.getText();
         sink.rawText(text == null ? "" : text);
 
         for (StructuralNode subNode : node.getBlocks()) {
@@ -61,14 +68,28 @@ public void process(StructuralNode node) {
             }
         }
 
-        if (isUnorderedListItem(item))
-            sink.listItem_();
-        else
-            sink.numberedListItem_();
+        switch (listType) {
+            case ordered:
+                sink.numberedListItem_();
+                break;
+            case unordered:
+                sink.listItem_();
+                break;
+        }
     }
 
-    private static boolean isUnorderedListItem(ListItem item) {
+    private static ListType getListType(ListItem item) {
         final String marker = item.getMarker();
-        return marker.startsWith("*") || marker.startsWith("-");
+        if (marker == null) {
+            return ListType.description;
+        } else if (marker.startsWith("*") || marker.startsWith("-")) {
+            return ListType.ordered;
+        } else {
+            return ListType.unordered;
+        }
+    }
+
+    enum ListType {
+        ordered, unordered, description
     }
 }