update generated properties reference (#4065)

Author: SylvainJuge

apm-agent-builds/apm-agent/src/test/java/co/elastic/apm/agent/configuration/ConfigurationExporter.java

@@ -44,7 +44,7 @@ public static void main(String[] args) throws Exception {
             ConfigurationRegistry configurationRegistry = ConfigurationRegistry.builder()
                 .optionProviders(ServiceLoader.load(ConfigurationOptionProvider.class))
                 .build();
-            Path path = Paths.get("docs/configuration.asciidoc");
+            Path path = Paths.get("docs/reference/config-reference-properties-file.md");
             if (!path.toFile().canWrite()) {
                 throw new IllegalStateException(path + " does not exist");
             }

apm-agent-builds/apm-agent/src/test/java/co/elastic/apm/agent/configuration/ConfigurationExporterTest.java

@@ -29,7 +29,6 @@
 import freemarker.template.TemplateExceptionHandler;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.stagemonitor.configuration.ConfigurationOption;
 import org.stagemonitor.configuration.ConfigurationOptionProvider;
@@ -41,6 +40,8 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
@@ -51,6 +52,7 @@
 import java.util.stream.Collectors;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.fail;
 import static org.mockito.Mockito.doReturn;
 import static org.mockito.Mockito.mock;
 
@@ -86,7 +88,7 @@ class ConfigurationExporterTest {
 
     @BeforeEach
     void setUp() {
-        renderedDocumentationPath = Paths.get("../../docs/configuration.asciidoc");
+        renderedDocumentationPath = Paths.get("../../docs/reference/config-reference-properties-file.md");
         ElasticApmTracer tracer = mock(ElasticApmTracer.class);
         doReturn(tracer).when(tracer).require(ElasticApmTracer.class);
         doReturn(ElasticApmTracer.TracerState.UNINITIALIZED).when(tracer).getState();
@@ -108,20 +110,33 @@ void tearDown() {
      * Since we allow a limited number of unit-test failures, this test would have always passed without this configuration.
      */
     @Test
-    @Disabled("Needs migration or update for new docs system")
     void testGeneratedConfigurationDocsAreUpToDate() throws IOException, TemplateException {
         String renderedDocumentation = renderDocumentation(configurationRegistry);
-        String expected = new String(Files.readAllBytes(this.renderedDocumentationPath), StandardCharsets.UTF_8);
+
+        // trim EOL whitespace
+        List<String> lines = new ArrayList<>(Arrays.asList(renderedDocumentation.split("\n")));
+        for (int i = 0; i < lines.size(); i++) {
+            lines.set(i, lines.get(i).replaceAll("\\s+$", ""));
+        }
+        // add extra empty line at end of file
+        lines.add("");
+        renderedDocumentation = String.join("\n", lines);
 
         if (Boolean.parseBoolean(System.getProperty("elastic.apm.overwrite.config.docs", Boolean.TRUE.toString()))) {
             // unless explicitly disabled (e.g. on CI) overwrite the current documentation
             Files.write(renderedDocumentationPath, renderedDocumentation.getBytes(StandardCharsets.UTF_8));
         }
 
+        if (!Files.exists(this.renderedDocumentationPath)) {
+            fail("rendered documentation file does not exists %s", this.renderedDocumentationPath.toAbsolutePath());
+        }
+
+        String expected = new String(Files.readAllBytes(this.renderedDocumentationPath), StandardCharsets.UTF_8);
+
         assertThat(renderedDocumentation)
             .withFailMessage("The rendered configuration documentation (/docs/configuration.asciidoc) is not up-to-date.\n" +
                 "If you see this error on CI, it means you have to execute the tests locally " +
-                "(./mvnw -Dsurefire.failIfNoTests=false -Dsurefire.failIfNoSpecifiedTests=false -Dtest=ConfigurationExporterTest -pl apm-agent -am clean test) " +
+                "(./mvnw -Dsurefire.failIfNoTests=false -Dsurefire.failIfNoSpecifiedTests=false -Dtest=ConfigurationExporterTest -pl apm-agent-builds/apm-agent -am clean test) " +
                 "or on Windows(.\\mvnw \"-Dsurefire.failIfNoTests=false\" \"-Dsurefire.failIfNoSpecifiedTests=false\" -Dtest=ConfigurationExporterTest -pl apm-agent-builds/apm-agent -am clean test) " +
                 "which will update the rendered docs.\n" +
                 "If you see this error while running the tests locally, there's nothing more to do - the rendered docs have been updated " +
@@ -136,13 +151,11 @@ static String renderDocumentation(ConfigurationRegistry configurationRegistry) t
         cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
         cfg.setLogTemplateExceptions(false);
 
-        Template temp = cfg.getTemplate("configuration.asciidoc.ftl");
+        // trim EOL whitespace
+        cfg.setWhitespaceStripping(true);
+
+        Template temp = cfg.getTemplate("config-reference-properties-file.md.ftl");
         StringWriter tempRenderedFile = new StringWriter();
-        tempRenderedFile.write("////\n" +
-            "This file is auto generated\n" +
-            "\n" +
-            "Please only make changes in configuration.asciidoc.ftl\n" +
-            "////\n");
         final List<ConfigurationOption<?>> nonInternalOptions = configurationRegistry.getConfigurationOptionsByCategory()
             .values()
             .stream()

apm-agent-builds/apm-agent/src/test/resources/config-reference-properties-file.md.ftl

@@ -0,0 +1,42 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/java/current/config-reference-properties-file.html
+---
+
+# Property file reference [config-reference-properties-file]
+
+```properties
+<#list config as category, options>
+############################################
+# ${category?right_pad(40)} #
+############################################
+
+    <#list options as option>
+        <#if !option.tags?seq_contains("internal")>
+<#if option.label?has_content>
+# ${option.label}
+#
+</#if>
+# ${option.description?replace("\n", "\n# ", "r")}
+#
+<#if option.validOptions?has_content>
+# Valid options: <#list option.validOptionsLabelMap?values as validOption>${validOption}<#if validOption_has_next>, </#if></#list>
+</#if>
+# ${option.dynamic?then("This setting can be changed at runtime",
+    "This setting can not be changed at runtime. Changes require a restart of the application.")}
+# Type: ${option.valueType?matches("List|Collection")?then("comma separated list", option.valueType)}
+<#if option.valueType?matches("TimeDuration")>
+  <#if option.valueConverter.canUseMicros>
+# Supports the duration suffixes us, ms, s and m. Example: ${option.defaultValueAsString}.
+  <#else>
+# Supports the duration suffixes ms, s and m. Example: ${option.defaultValueAsString}.
+  </#if>
+</#if>
+# Default value: ${option.key?matches("service_name")?then('Auto-detected based on the rules described above', option.defaultValueAsString!)}
+#
+# ${option.key}=${option.key?matches("service_name")?then('', option.defaultValueAsString!)}
+
+        </#if>
+    </#list>
+</#list>
+```

apm-agent-builds/apm-agent/src/test/resources/configuration.asciidoc.ftl

@@ -636,7 +636,7 @@ public String toSafeString(List<WildcardMatcher> value) {
             "\n" +
             "A few examples:\n" +
             "\n" +
-            " - `org.example.*` added[1.4.0,Omitting the method is possible since 1.4.0]\n" +
+            " - `org.example.*` added:[1.4.0,Omitting the method is possible since 1.4.0]\n" +
             " - `org.example.*#*` (before 1.4.0, you need to specify a method matcher)\n" +
             " - `org.example.MyClass#myMethod`\n" +
             " - `org.example.MyClass#myMethod()`\n" +