Add "micrometer-docs-generator" module (#40)

Add a new module "micrometer-docs-generator" which combines existing
commons, metrics, and spans modules.

In this module, `DocsGeneratorCommand` is the entry point to execute
the document generation.

By default, it generates all `_metrics.adoc`, `_spans.adoc`, and
`_conventions.adoc` files.  The command takes `--metrics`, `--spans`,
`--conventions` optional arguments.  Once these options are provided,
only specified docs are generated.

dependencies.gradle

@@ -2,6 +2,7 @@ def VERSIONS = [
 	'org.jboss.forge.roaster:roaster-api:2.22.3.Final', // last using jdk8
 	'org.jboss.forge.roaster:roaster-jdt:2.22.3.Final', // last using jdk8
 	'com.github.jknack:handlebars:latest.release',
+	'info.picocli:picocli:latest.release',
 
 	// logging
 	'ch.qos.logback:logback-classic:1.2.+',

micrometer-docs-generator/build.gradle

@@ -0,0 +1,19 @@
+plugins {
+	id 'idea'
+}
+
+dependencies {
+	api 'io.micrometer:micrometer-observation'
+	api 'io.micrometer:micrometer-core'
+	api 'io.micrometer:micrometer-tracing'
+	api 'org.jboss.forge.roaster:roaster-api'
+	api 'org.jboss.forge.roaster:roaster-jdt'
+	api 'ch.qos.logback:logback-classic'
+	api 'info.picocli:picocli'
+	api 'com.github.jknack:handlebars'
+
+	testImplementation 'org.junit.jupiter:junit-jupiter'
+	testImplementation 'org.assertj:assertj-core'
+	testImplementation 'org.mockito:mockito-core'
+}
+

micrometer-docs-generator/src/main/java/io/micrometer/docs/DocsGeneratorCommand.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.micrometer.docs;
+
+import java.io.File;
+import java.util.regex.Pattern;
+
+import io.micrometer.common.util.internal.logging.InternalLogger;
+import io.micrometer.common.util.internal.logging.InternalLoggerFactory;
+import io.micrometer.docs.conventions.ObservationConventionsDocGenerator;
+import io.micrometer.docs.metrics.MetricsDocGenerator;
+import io.micrometer.docs.spans.SpansDocGenerator;
+import picocli.CommandLine;
+import picocli.CommandLine.ArgGroup;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+import picocli.CommandLine.Parameters;
+
+/**
+ * Entry point for document generation.
+ *
+ * @author Tadaya Tsuyukubo
+ */
+@Command(mixinStandardHelpOptions = true, description = "Generate documentation from source files")
+public class DocsGeneratorCommand implements Runnable {
+
+    private static final InternalLogger logger = InternalLoggerFactory.getInstance(DocsGeneratorCommand.class);
+
+    @ArgGroup(exclusive = false)
+    private final Options options = new Options();
+
+    @Parameters(index = "0", description = "The project root directory.")
+    private File projectRoot;
+
+    @Parameters(index = "1", description = "The regex pattern for inclusion.")
+    private Pattern inclusionPattern;
+
+    @Parameters(index = "2", description = "The output directory.")
+    private File outputDir;
+
+    public static void main(String... args) {
+        new CommandLine(new DocsGeneratorCommand()).execute(args);
+        // Do not call System.exit here since exec-maven-plugin stops the maven run
+    }
+
+    @Override
+    public void run() {
+        this.inclusionPattern = Pattern.compile(this.inclusionPattern.pattern().replace("/", File.separator));
+        logger.info("Project root: {}", this.projectRoot);
+        logger.info("Inclusion pattern: {}", this.inclusionPattern);
+        logger.info("Output root: {}", this.outputDir);
+
+        this.options.setAllIfNoneSpecified();
+        if (this.options.metrics) {
+            generateMetricsDoc();
+        }
+        if (this.options.spans) {
+            generateSpansDoc();
+        }
+        if (this.options.conventions) {
+            generateConventionsDoc();
+        }
+    }
+
+    void generateMetricsDoc() {
+        new MetricsDocGenerator(this.projectRoot, this.inclusionPattern, this.outputDir).generate();
+    }
+
+    void generateSpansDoc() {
+        new SpansDocGenerator(this.projectRoot, this.inclusionPattern, this.outputDir).generate();
+    }
+
+    void generateConventionsDoc() {
+        new ObservationConventionsDocGenerator(this.projectRoot, this.inclusionPattern, this.outputDir).generate();
+    }
+
+    static class Options {
+        @Option(names = "--metrics", description = "Generate metrics documentation")
+        private boolean metrics;
+
+        @Option(names = "--spans", description = "Generate spans documentation")
+        private boolean spans;
+
+        @Option(names = "--conventions", description = "Generate conventions documentation")
+        private boolean conventions;
+
+        void setAllIfNoneSpecified() {
+            if (!this.metrics && !this.spans && !this.conventions) {
+                this.metrics = true;
+                this.spans = true;
+                this.conventions = true;
+            }
+        }
+
+    }
+}

micrometer-docs-generator/src/main/java/io/micrometer/docs/commons/KeyValueEntry.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2013-2020 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.micrometer.docs.commons;
+
+import java.util.Objects;
+
+public class KeyValueEntry implements Comparable<KeyValueEntry> {
+
+    private final String name;
+
+    private final String description;
+
+    public KeyValueEntry(String name, String description) {
+        this.name = name;
+        this.description = description;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        KeyValueEntry tag = (KeyValueEntry) o;
+        return Objects.equals(name, tag.name) && Objects.equals(description, tag.description);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(name, description);
+    }
+
+    @Override
+    public int compareTo(KeyValueEntry o) {
+        return name.compareTo(o.name);
+    }
+
+    @Override
+    public String toString() {
+        return "|`" + name + "`|" + description();
+    }
+
+    private String description() {
+        String suffix = "";
+        if (this.name.contains("%s")) {
+            suffix = " (since the name contains `%s` the final value will be resolved at runtime)";
+        }
+        return description + suffix;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public String getDescription() {
+        return description;
+    }
+
+    public String getDisplayDescription() {
+        // TODO: use handlebar helper to compose the description
+        return description();
+    }
+}