generate a documentation file for each config root and general config…

… items (non config group Fixes quarkusio#5144 Follows up quarkusio#5044
machi1990 · Nov 24, 2019 · 3deedec · 3deedec
1 parent 21cd452
commit 3deedec
Show file tree

Hide file tree

Showing 15 changed files with 344 additions and 135 deletions.
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java
@@ -17,7 +17,6 @@ final public class Constants {
     public static final char DOT = '.';
     public static final String EMPTY = "";
     public static final String DASH = "-";
-    public static final String CORE = "core-";
     public static final String ADOC_EXTENSION = ".adoc";
     public static final String DIGIT_OR_LOWERCASE = "^[a-z0-9]+$";
 

diff --git a/...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java b/...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java
@@ -65,9 +65,10 @@
 import org.jboss.jdeparser.JType;
 import org.jboss.jdeparser.JTypes;
 
+import io.quarkus.annotation.processor.generate_doc.ConfigDocGeneratedOutput;
 import io.quarkus.annotation.processor.generate_doc.ConfigDocItemScanner;
 import io.quarkus.annotation.processor.generate_doc.ConfigDocWriter;
-import io.quarkus.annotation.processor.generate_doc.ScannedConfigDocsItemHolder;
+import io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil;
 
 public class ExtensionAnnotationProcessor extends AbstractProcessor {
 
@@ -235,12 +236,12 @@ public FileVisitResult postVisitDirectory(final Path dir, final IOException exc)
         }
 
         try {
-            final ScannedConfigDocsItemHolder scannedConfigDocsItemHolder = configDocItemScanner
+            final Set<ConfigDocGeneratedOutput> outputs = configDocItemScanner
                     .scanExtensionsConfigurationItems(javaDocProperties);
-
-            configDocWriter.writeExtensionConfigDocumentation(scannedConfigDocsItemHolder.getAllConfigItemsPerExtension(),
-                    true); // generate extension doc with search engine activate
-            configDocWriter.writeExtensionConfigDocumentation(scannedConfigDocsItemHolder.getConfigGroupConfigItems(), false); // generate config group docs with search engine deactivated
+            for (ConfigDocGeneratedOutput output : outputs) {
+                DocGeneratorUtil.sort(output.getConfigDocItems()); // sort before writing
+                configDocWriter.writeAllExtensionConfigDocumentation(output);
+            }
         } catch (IOException e) {
             processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Failed to generate extension doc: " + e);
             return;

diff --git a/...cessor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java b/...cessor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDoItemFinder.java
@@ -57,7 +57,7 @@ ScannedConfigDocsItemHolder findInMemoryConfigurationItems() {
             final int sectionLevel = 2;
             final List<ConfigDocItem> configDocItems = recursivelyFindConfigItems(element, configRootInfo.getName(),
                     configRootInfo.getConfigPhase(), false, sectionLevel);
-            holder.addToAllConfigItems(configRootInfo.getClazz().getQualifiedName().toString(), configDocItems);
+            holder.addConfigRootItems(configRootInfo.getClazz().getQualifiedName().toString(), configDocItems);
         }
 
         return holder;
@@ -227,6 +227,7 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String p
                 configDocKey.setType(type);
                 configDocKey.setList(list);
                 configDocKey.setOptional(optional);
+                configDocKey.setWithinAConfigGroup(sectionLevel > 2);
                 configDocKey.setConfigPhase(configPhase);
                 configDocKey.setDefaultValue(defaultValue);
                 configDocKey.setDocMapKey(configDocMapKey);
@@ -244,19 +245,16 @@ private List<ConfigDocItem> recursivelyFindConfigItems(Element element, String p
 
     private List<ConfigDocItem> recordConfigItemsFromConfigGroup(ConfigPhase configPhase, String name, Element configGroup,
             ConfigDocSection configSection, boolean withinAMap, int sectionLevel) {
-        final List<ConfigDocItem> groupConfigItems;
         final List<ConfigDocItem> configDocItems = new ArrayList<>();
-
-        if (configSection != null) {
+        final List<ConfigDocItem> groupConfigItems = recursivelyFindConfigItems(configGroup, name, configPhase, withinAMap,
+                sectionLevel + 1);
+        if (configSection == null) {
+            configDocItems.addAll(groupConfigItems);
+        } else {
             final ConfigDocItem configDocItem = new ConfigDocItem();
             configDocItem.setConfigDocSection(configSection);
             configDocItems.add(configDocItem);
-            groupConfigItems = recursivelyFindConfigItems(configGroup, name, configPhase, withinAMap,
-                    sectionLevel + 1);
             configSection.addConfigDocItems(groupConfigItems);
-        } else {
-            groupConfigItems = recursivelyFindConfigItems(configGroup, name, configPhase, withinAMap, sectionLevel);
-            configDocItems.addAll(groupConfigItems);
         }
 
         String configGroupName = configGroup.asType().toString();

diff --git a/.../src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocGeneratedOutput.java b/.../src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocGeneratedOutput.java
@@ -0,0 +1,70 @@
+package io.quarkus.annotation.processor.generate_doc;
+
+import java.util.List;
+import java.util.Objects;
+
+import io.quarkus.annotation.processor.Constants;
+
+public class ConfigDocGeneratedOutput {
+    private final String fileName;
+    private final boolean searchable;
+    private final boolean hasAnchorPrefix;
+    private final List<ConfigDocItem> configDocItems;
+
+    public ConfigDocGeneratedOutput(String fileName, boolean searchable, List<ConfigDocItem> configDocItems,
+            boolean hasAnchorPrefix) {
+        this.fileName = fileName;
+        this.searchable = searchable;
+        this.configDocItems = configDocItems;
+        this.hasAnchorPrefix = hasAnchorPrefix;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+
+    public boolean isSearchable() {
+        return searchable;
+    }
+
+    public List<ConfigDocItem> getConfigDocItems() {
+        return configDocItems;
+    }
+
+    public String getAnchorPrefix() {
+        if (!hasAnchorPrefix) {
+            return Constants.EMPTY;
+        }
+
+        String anchorPrefix = fileName;
+        if (fileName.endsWith(Constants.ADOC_EXTENSION)) {
+            anchorPrefix = anchorPrefix.substring(0, anchorPrefix.length() - 5);
+        }
+
+        return anchorPrefix + "_";
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o)
+            return true;
+        if (o == null || getClass() != o.getClass())
+            return false;
+        ConfigDocGeneratedOutput that = (ConfigDocGeneratedOutput) o;
+        return Objects.equals(fileName, that.fileName);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(fileName);
+    }
+
+    @Override
+    public String toString() {
+        return "ConfigItemsOutput{" +
+                "fileName='" + fileName + '\'' +
+                ", searchable=" + searchable +
+                ", configDocItems=" + configDocItems +
+                '}';
+    }
+}
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItem.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItem.java
@@ -89,6 +89,17 @@ public boolean isWithinAMap() {
         return false;
     }
 
+    @JsonIgnore
+    public boolean isWithinAConfigGroup() {
+        if (isConfigSection()) {
+            return true;
+        } else if (isConfigKey() && configDocKey.isWithinAConfigGroup()) {
+            return true;
+        }
+
+        return false;
+    }
+
     /**
      * TODO determine section ordering
      *

diff --git a/...ssor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java b/...ssor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java
@@ -1,6 +1,7 @@
 package io.quarkus.annotation.processor.generate_doc;
 
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.computeConfigGroupDocFileName;
+import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.computeConfigRootDocFileName;
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.computeExtensionDocFileName;
 import static io.quarkus.annotation.processor.generate_doc.DocGeneratorUtil.deriveConfigRootName;
 
@@ -98,15 +99,11 @@ public void addConfigRoot(final PackageElement pkg, TypeElement clazz) {
         }
     }
 
-    /**
-     * Return a data structure which contains two maps of config items.
-     * 1. A map of all extensions config items accessible via
-     * {@link ScannedConfigDocsItemHolder#getAllConfigItemsPerExtension()}
-     * 2. a map of all config groups config items accessible via {@link ScannedConfigDocsItemHolder#getConfigGroupConfigItems()}
-     */
-    public ScannedConfigDocsItemHolder scanExtensionsConfigurationItems(Properties javaDocProperties)
+    public Set<ConfigDocGeneratedOutput> scanExtensionsConfigurationItems(Properties javaDocProperties)
             throws IOException {
 
+        Set<ConfigDocGeneratedOutput> configDocGeneratedOutputs = new HashSet<>();
+
         final ConfigDoItemFinder configDoItemFinder = new ConfigDoItemFinder(configRoots, configGroups, javaDocProperties);
         final ScannedConfigDocsItemHolder inMemoryScannedItemsHolder = configDoItemFinder.findInMemoryConfigurationItems();
 
@@ -122,11 +119,16 @@ public ScannedConfigDocsItemHolder scanExtensionsConfigurationItems(Properties j
                     configurationRootsParExtensionFileName);
         }
 
-        Map<String, List<ConfigDocItem>> allConfigItemsPerExtension = computeAllExtensionConfigItems(inMemoryScannedItemsHolder,
+        Set<ConfigDocGeneratedOutput> allConfigItemsPerExtension = generateAllConfigItemsOutputs(inMemoryScannedItemsHolder,
                 allExtensionGeneratedDocs, configurationRootsParExtensionFileName);
-        Map<String, List<ConfigDocItem>> configGroupConfigItems = computeConfigGroupFilesNames(inMemoryScannedItemsHolder);
+        Set<ConfigDocGeneratedOutput> configGroupConfigItems = generateAllConfigGroupOutputs(inMemoryScannedItemsHolder);
+        Set<ConfigDocGeneratedOutput> configRootConfigItems = generateAllConfigRootOutputs(inMemoryScannedItemsHolder);
 
-        return new ScannedConfigDocsItemHolder(allConfigItemsPerExtension, configGroupConfigItems);
+        configDocGeneratedOutputs.addAll(configGroupConfigItems);
+        configDocGeneratedOutputs.addAll(allConfigItemsPerExtension);
+        configDocGeneratedOutputs.addAll(configRootConfigItems);
+
+        return configDocGeneratedOutputs;
     }
 
     private void createOutputFolder() throws IOException {
@@ -196,7 +198,7 @@ private void updateConfigurationRootsList(Properties configurationRootsParExtens
 
     private void updateScannedExtensionArtifactFiles(ScannedConfigDocsItemHolder inMemoryScannedItemsHolder,
             Properties allExtensionGeneratedDocs, Properties configurationRootsParExtensionFileName) throws IOException {
-        for (Map.Entry<String, List<ConfigDocItem>> entry : inMemoryScannedItemsHolder.getAllConfigItemsPerExtension()
+        for (Map.Entry<String, List<ConfigDocItem>> entry : inMemoryScannedItemsHolder.getConfigRootConfigItems()
                 .entrySet()) {
             String serializableConfigRootDoc = OBJECT_MAPPER.writeValueAsString(entry.getValue());
             allExtensionGeneratedDocs.put(entry.getKey(), serializableConfigRootDoc);
@@ -220,13 +222,10 @@ private void updateScannedExtensionArtifactFiles(ScannedConfigDocsItemHolder inM
         }
     }
 
-    /**
-     * returns a Map of with extension generated file name and the list of its associated config items.
-     */
-    private Map<String, List<ConfigDocItem>> computeAllExtensionConfigItems(
+    private Set<ConfigDocGeneratedOutput> generateAllConfigItemsOutputs(
             ScannedConfigDocsItemHolder inMemoryScannedItemsHolder, Properties allExtensionGeneratedDocs,
             Properties configurationRootsParExtensionFileName) throws IOException {
-        Map<String, List<ConfigDocItem>> configItemsParExtensionFileNames = new HashMap<>();
+        Set<ConfigDocGeneratedOutput> outputs = new HashSet<>();
 
         Set<String> extensionFileNamesToGenerate = processorClassMembers
                 .stream()
@@ -241,35 +240,59 @@ private Map<String, List<ConfigDocItem>> computeAllExtensionConfigItems(
             }
 
             String[] extensionConfigRoots = extensionConfigRootsProperty.split(EXTENSION_LIST_SEPARATOR);
+            List<ConfigDocItem> extensionConfigItems = new ArrayList<>();
+
             for (String configRoot : extensionConfigRoots) {
-                List<ConfigDocItem> configDocItems = inMemoryScannedItemsHolder.getAllConfigItemsPerExtension().get(configRoot);
+                List<ConfigDocItem> configDocItems = inMemoryScannedItemsHolder.getConfigRootConfigItems().get(configRoot);
                 if (configDocItems == null) {
                     String serializedContent = allExtensionGeneratedDocs.getProperty(configRoot);
                     configDocItems = OBJECT_MAPPER.readValue(serializedContent, new TypeReference<List<ConfigDocItem>>() {
                     });
                 }
 
-                final List<ConfigDocItem> existingConfigDocItems = configItemsParExtensionFileNames
-                        .computeIfAbsent(extensionFileName, (key) -> new ArrayList<>());
-                DocGeneratorUtil.appendConfigItemsIntoExistingOnes(existingConfigDocItems, configDocItems);
+                DocGeneratorUtil.appendConfigItemsIntoExistingOnes(extensionConfigItems, configDocItems);
             }
+
+            outputs.add(new ConfigDocGeneratedOutput(extensionFileName, true, extensionConfigItems, true));
+
+            List<ConfigDocItem> generalConfigItems = extensionConfigItems
+                    .stream()
+                    .filter(ConfigDocItem::isWithinAConfigGroup)
+                    .collect(Collectors.toList());
+
+            if (!generalConfigItems.isEmpty()) {
+                String fileName = extensionFileName.replaceAll("\\.adoc$", "-general-config-items.adoc");
+                outputs.add(new ConfigDocGeneratedOutput(fileName, false, generalConfigItems, true));
+            }
+
         }
 
-        return configItemsParExtensionFileNames;
+        return outputs;
     }
 
-    /**
-     * returns a Map of with config group generated file name and the list of its associated config items.
-     */
-    private Map<String, List<ConfigDocItem>> computeConfigGroupFilesNames(
+    private Set<ConfigDocGeneratedOutput> generateAllConfigGroupOutputs(
             ScannedConfigDocsItemHolder inMemoryScannedItemsHolder) {
-        Map<String, List<ConfigDocItem>> configItemsParConfigGroupFileNames = new HashMap<>();
-        for (Map.Entry<String, List<ConfigDocItem>> entry : inMemoryScannedItemsHolder.getConfigGroupConfigItems().entrySet()) {
-            String extensionDocFileName = computeConfigGroupDocFileName(entry.getKey());
-            configItemsParConfigGroupFileNames.put(extensionDocFileName, entry.getValue());
+
+        return inMemoryScannedItemsHolder
+                .getConfigGroupConfigItems()
+                .entrySet()
+                .stream()
+                .map(entry -> new ConfigDocGeneratedOutput(computeConfigGroupDocFileName(entry.getKey()), false,
+                        entry.getValue(), true))
+                .collect(Collectors.toSet());
+    }
+
+    private Set<ConfigDocGeneratedOutput> generateAllConfigRootOutputs(ScannedConfigDocsItemHolder inMemoryScannedItemsHolder) {
+        Map<String, List<ConfigDocItem>> configRootConfigItems = inMemoryScannedItemsHolder.getConfigRootConfigItems();
+        Set<ConfigDocGeneratedOutput> outputs = new HashSet<>();
+        for (ConfigRootInfo configRootInfo : configRoots) {
+            String clazz = configRootInfo.getClazz().getQualifiedName().toString();
+            List<ConfigDocItem> configDocItems = configRootConfigItems.get(clazz);
+            String fileName = computeConfigRootDocFileName(clazz, configRootInfo.getName());
+            outputs.add(new ConfigDocGeneratedOutput(fileName, false, configDocItems, true));
         }
 
-        return configItemsParConfigGroupFileNames;
+        return outputs;
     }
 
     /**

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocKey.java
@@ -21,6 +21,7 @@ final public class ConfigDocKey implements ConfigDocElement, Comparable<ConfigDo
     private boolean optional;
     private boolean list;
     private boolean passThroughMap;
+    private boolean withinAConfigGroup;
 
     public ConfigDocKey() {
     }
@@ -155,6 +156,14 @@ public void setPassThroughMap(boolean passThroughMap) {
         this.passThroughMap = passThroughMap;
     }
 
+    public boolean isWithinAConfigGroup() {
+        return withinAConfigGroup;
+    }
+
+    public void setWithinAConfigGroup(boolean withinAConfigGroup) {
+        this.withinAConfigGroup = withinAConfigGroup;
+    }
+
     @Override
     public void accept(Writer writer, DocFormatter docFormatter) throws IOException {
         docFormatter.format(writer, this);
@@ -176,6 +185,7 @@ public boolean equals(Object o) {
                 optional == that.optional &&
                 list == that.list &&
                 passThroughMap == that.passThroughMap &&
+                withinAConfigGroup == that.withinAConfigGroup &&
                 Objects.equals(type, that.type) &&
                 Objects.equals(key, that.key) &&
                 Objects.equals(configDoc, that.configDoc) &&
@@ -189,7 +199,7 @@ public boolean equals(Object o) {
     @Override
     public int hashCode() {
         return Objects.hash(type, key, configDoc, withinAMap, defaultValue, javaDocSiteLink, docMapKey, configPhase,
-                acceptedValues, optional, list, passThroughMap);
+                acceptedValues, optional, list, passThroughMap, withinAConfigGroup);
     }
 
     @Override
@@ -207,6 +217,7 @@ public String toString() {
                 ", optional=" + optional +
                 ", list=" + list +
                 ", passThroughMap=" + passThroughMap +
+                ", withinAConfigGroup=" + withinAConfigGroup +
                 '}';
     }
 }