[MSITE-1000] Introduce parser configuration parameter

pom.xml

@@ -198,8 +198,8 @@ under the License.
     <javaVersion>8</javaVersion>
     <!-- for dependencies -->
     <jettyVersion>9.4.53.v20231009</jettyVersion>
-    <doxiaVersion>2.0.0-M8</doxiaVersion>
-    <doxiaSitetoolsVersion>2.0.0-M16</doxiaSitetoolsVersion>
+    <doxiaVersion>2.0.0-M9-SNAPSHOT</doxiaVersion>
+    <doxiaSitetoolsVersion>2.0.0-M17-SNAPSHOT</doxiaSitetoolsVersion>
     <wagonVersion>3.5.3</wagonVersion>
     <slf4jVersion>1.7.36</slf4jVersion>
     <!-- for ITs -->
@@ -513,6 +513,17 @@ under the License.
   <build>
     <pluginManagement>
       <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-plugin-plugin</artifactId>
+          <configuration>
+            <externalJavadocBaseUrls>
+              <externalJavadocBaseUrl>https://maven.apache.org/doxia/doxia/doxia-core/apidocs/</externalJavadocBaseUrl>
+              <externalJavadocBaseUrl>https://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/apidocs/</externalJavadocBaseUrl>
+              <externalJavadocBaseUrl>https://docs.oracle.com/javase/8/docs/api/</externalJavadocBaseUrl>
+            </externalJavadocBaseUrls>
+          </configuration>
+        </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-plugin-report-plugin</artifactId>

src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java

@@ -94,6 +94,25 @@ public abstract class AbstractSiteRenderingMojo extends AbstractSiteDescriptorMo
     @Parameter
     private Map<String, Object> attributes;
 
+    /**
+     * Parser configurations (per matching Doxia markup source file path patterns).
+     * Each configuration item has the following format:
+     * <p/>
+     * <pre>
+     *   &lt;patterns&gt;
+     *     &lt;pattern&gt;glob:**&#47;*.md&lt;/pattern&gt;&lt;!-- is either glob or regex syntax with the according prefix --&gt;
+     *   &lt;/patterns&gt;
+     *   &lt;emitComments&gt;true&lt;/emitComments&gt;&lt;!-- false by default --&gt;
+     *   &lt;emitAnchorsForIndexableEntries&gt;false&lt;/emitAnchorsForIndexableEntries&gt;&lt;!-- true by default --&gt;
+     * </pre>
+     * The configuration is only applied if one of the given patterns matches the Doxia markup source file path.
+     * The first matching configuration wins (i.e. is applied).
+     * @since 4.0.0
+     * @see java.nio.file.FileSystem#getPathMatcher(String) FileSystem.getPathMatcher(String) for the supported patterns
+     */
+    @Parameter
+    private List<ParserConfiguration> parserConfigurations;
+
     /**
      * Site renderer.
      */
@@ -329,7 +348,7 @@ protected SiteRenderingContext createSiteRenderingContext(Locale locale)
                 context.setProcessedContentOutput(processedDir);
             }
         }
-
+        context.setParserConfigurationRetriever(new ParserConfigurationRetrieverImpl(parserConfigurations));
         return context;
     }
 

src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java

@@ -0,0 +1,119 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *   http://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 org.apache.maven.plugins.site.render;
+
+import java.nio.file.FileSystem;
+import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+import org.apache.maven.doxia.parser.Parser;
+
+/** Configuration for a Doxia {@link Parser} (bound to a specific markup source path pattern)
+ * @since 4.0.0
+ **/
+public class ParserConfiguration implements org.apache.maven.doxia.siterenderer.ParserConfiguration {
+
+    /**
+     * List of patterns in the format described at {@link FileSystem#getPathMatcher(String)}, i.e. {@code <syntax>:<pattern>}
+     * where {@code <syntax} is either {@code glob} or {@code regex}.
+     * If one of the patterns matches the file being parsed this configuration is applied.
+     * @see FileSystem#getPathMatcher(String)
+     * @see Pattern
+     */
+    private final List<String> patterns;
+
+    /**
+     * List of {@link PathMatcher}s for all of the {@link #patterns}. Lazily populated via {@link FileSystem#getPathMatcher(String)}.
+     */
+    private List<PathMatcher> matchers;
+
+    private boolean emitComments;
+
+    private boolean emitAnchorsForIndexableEntries;
+
+    public ParserConfiguration() {
+        patterns = new LinkedList<>();
+        matchers = null;
+    }
+
+    /**
+     * Switches the feature {@link Parser#setEmitComments(boolean)} either on or off.
+     * Default (for Doxia Sitetools) is off.
+     *
+     * @param emitComments {@code true} to switch it on, otherwise leave it off
+     * @see Parser#setEmitComments(boolean)
+     */
+    public void setEmitComments(boolean emitComments) {
+        this.emitComments = emitComments;
+    }
+
+    /**
+     * Switches the feature {@link Parser#setEmitAnchorsForIndexableEntries(boolean)} either on or off.
+     * Default (for Doxia Sitetools) is on.
+     *
+     * @param emitAnchorsForIndexableEntries {@code true} to switch it on, otherwise leave it off
+     * @see Parser#setEmitAnchorsForIndexableEntries(boolean)
+     */
+    public void setEmitAnchorsForIndexableEntries(boolean emitAnchorsForIndexableEntries) {
+        this.emitAnchorsForIndexableEntries = emitAnchorsForIndexableEntries;
+    }
+
+    /**
+     * A pattern in the format described at {@link FileSystem#getPathMatcher(String)}, i.e. {@code <syntax>:<pattern>}
+     * where {@code <syntax} is either {@code glob} or {@code regex}.
+     * If one of the patterns matches the file being parsed this configuration is applied.
+     * @see FileSystem#getPathMatcher(String)
+     * @see Pattern
+     */
+    public void addPattern(String pattern) {
+        patterns.add(pattern);
+    }
+
+    /**
+     * Returns {@code true} the given file path matches one of the {@link #patterns} given via {@link #addPattern(String)}
+     * @param filePath the file path to check
+     * @return {@code true} if the given file path matches at least one of the patterns, {@code false} otherwise.
+     * @throws  IllegalArgumentException
+     *          If one of the patterns does not comply with the form: {@code syntax:pattern}
+     * @throws  java.util.regex.PatternSyntaxException
+     *          If one of the regex patterns is invalid
+     * @throws  UnsupportedOperationException
+     *          If one of the patterns syntax prefix is not known to the implementation
+     * @see FileSystem#getPathMatcher(String)
+     */
+    public boolean matches(Path filePath) {
+        if (matchers == null) {
+            // lazily populate all matchers
+            matchers = patterns.stream()
+                    .map(p -> filePath.getFileSystem().getPathMatcher(p))
+                    .collect(Collectors.toList());
+        }
+        return matchers.stream().anyMatch(m -> m.matches(filePath));
+    }
+
+    @Override
+    public void configure(Parser parser) {
+        parser.setEmitComments(emitComments);
+        parser.setEmitAnchorsForIndexableEntries(emitAnchorsForIndexableEntries);
+    }
+}

src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *   http://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 org.apache.maven.plugins.site.render;
+
+import java.nio.file.Path;
+import java.util.Collection;
+import java.util.Optional;
+
+import org.apache.maven.doxia.siterenderer.ParserConfigurationRetriever;
+
+public class ParserConfigurationRetrieverImpl implements ParserConfigurationRetriever {
+
+    private final Collection<ParserConfiguration> parserConfigurations;
+
+    public ParserConfigurationRetrieverImpl(Collection<ParserConfiguration> parserConfigurations) {
+        this.parserConfigurations = parserConfigurations;
+    }
+
+    @Override
+    public Optional<org.apache.maven.doxia.siterenderer.ParserConfiguration> retrieve(Path filePath) {
+        return parserConfigurations.stream()
+                .filter(c -> c.matches(filePath))
+                .findFirst()
+                .map(c -> c);
+    }
+}

src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java

@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *   http://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 org.apache.maven.plugins.site.render;
+
+import java.nio.file.Paths;
+import java.util.Arrays;
+import java.util.Optional;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+
+public class ParserConfigurationRetrieverImplTest {
+
+    @Test
+    public void testEmptyConfigurations() {
+        ParserConfiguration config1 = new ParserConfiguration();
+        ParserConfiguration config2 = new ParserConfiguration();
+        assertEquals(
+                Optional.empty(),
+                new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2))
+                        .retrieve(Paths.get("some", "file")));
+    }
+
+    @Test
+    public void testConfigurationWithInvalidPattern() {
+        ParserConfiguration config1 = new ParserConfiguration();
+        config1.addPattern("invalidprefix:*");
+        ParserConfigurationRetrieverImpl parserConfigurationRetrieverImpl =
+                new ParserConfigurationRetrieverImpl(Arrays.asList(config1));
+        assertThrows(RuntimeException.class, () -> {
+            parserConfigurationRetrieverImpl.retrieve(Paths.get("some", "file"));
+        });
+    }
+
+    @Test
+    public void testNonMatchingConfigurations() {
+        ParserConfiguration config1 = new ParserConfiguration();
+        config1.addPattern("glob:**/*.md");
+        ParserConfiguration config2 = new ParserConfiguration();
+        config2.addPattern("regex:.*\\.apt");
+        assertEquals(
+                Optional.empty(),
+                new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2))
+                        .retrieve(Paths.get("some", "file")));
+    }
+
+    @Test
+    public void testNonOverlappingConfigurations() {
+        ParserConfiguration config1 = new ParserConfiguration();
+        config1.addPattern("regex:.*\\.apt");
+        ParserConfiguration config2 = new ParserConfiguration();
+        config2.addPattern("glob:**/*");
+        assertEquals(
+                Optional.of(config2),
+                new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2))
+                        .retrieve(Paths.get("some", "file")));
+    }
+
+    @Test
+    public void testOverlappingConfigurations() {
+        ParserConfiguration config1 = new ParserConfiguration();
+        config1.addPattern("glob:**/*");
+        ParserConfiguration config2 = new ParserConfiguration();
+        config2.addPattern("regex:.*");
+        assertEquals(
+                Optional.of(config1),
+                new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2))
+                        .retrieve(Paths.get("some", "file")));
+    }
+}