[MSITE-1000] Allow parametrisation of Doxia parser per file

[jira-importer]

Konrad Windszus opened MSITE-1000 and commented

Currently only the attributes used for rendering the site can be parameterized in https://maven.apache.org/plugins/maven-site-plugin/site-mojo.html#attributes. There is no possibility to configure the parser in https://github.com/apache/maven-doxia-sitetools/blob/dacaa552c1b8e89eed84db0f43b6b0a72be91d0c/doxia-site-renderer/src/main/java/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.java#L322 per document.

This would be nice in the context of https://issues.apache.org/jira/browse/DOXIA-722 where generation of anchors should be switched on/off for certain documents. Also generation of comments may be desirable for certain documents.

I propose the following additional plugin goal parameter:

<parserConfigurations>
  <parserConfiguration>
    <patterns>
      <pattern>**/apt/**</pattern>
    </patterns>
    <emitAnchorsForIndexableEntries>false</emitAnchorsForIndexableEntries>
    <emitComments>true</emitComments>
  </parserConfiguration>
<parserConfigurations>

where parserConfigurations is an array of a complex type with (include) patterns on the source path (String array) and boolean methods for features.

This also required an upgrade to Maven Plugin Tools 3.13.0.

---

Issue Links:

• DOXIASITETOOLS-324 Allow configuration of parser per markup
  ("is blocked by")
• DOXIA-722 Optionally create anchors for indexable entries (used in TOC macro)

Remote Links:

• GitHub Pull Request #171
  
• GitHub Pull Request #177
  

[jira-importer]

Michael Osipov commented

Congrats for creation the thousandth issue!

[jira-importer]

Abel Salgado Romero commented

If I understand, this story is to allow clean configuration of other modules. If it helps, you can have a look at how we hacked our way around the limitations. It's similar to the proposal. This improvement is very appreciated and I look forward to seeing this completed.

Here is how we do it, we added a custom element <asciidoc> to the configuration, which we simply parsed by hand accessing the POM's XML (obviously IDE complain, but it works):

• Get Xpp3Dom https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/80c699035933aae133afaf9592bcc065c3d41b74/src/main/java/org/asciidoctor/maven/site/AsciidoctorDoxiaParser.java#L106-L108
• Parse XML by hand to generate converted API object https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/80c699035933aae133afaf9592bcc065c3d41b74/src/main/java/org/asciidoctor/maven/site/SiteConversionConfigurationParser.java#L46-L80
• Pass the specific API object to the converter https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/80c699035933aae133afaf9592bcc065c3d41b74/src/main/java/org/asciidoctor/maven/site/AsciidoctorDoxiaParser.java#L79

The parser configuration is varied, strings (some could be enums), booleans, and free key-value maps.

My only issue with the example is parserConfigurations, there should be a way to identify the config owner, you could have AsciiDoc and MarkDown and each one requires different configuation. I like having the tag be called <asciidoc>

<parserConfigurations>
  <asciidoc>
    <patterns>
      <pattern>*{*}/apt/{*}*</pattern>
    </patterns>
  </asciidoc>
  <markdown>
    <patterns>
      <pattern>*{*}/apt/{*}*</pattern>
    </patterns>
  </markdown>
<parserConfigurations>

 

Instead of something with a tag like:

 

<parserConfigurations>
  <parserConfiguration>
    <parser>asciidoc</parser>
    <patterns>
      <pattern>*{*}/apt/{*}*</pattern>
    </patterns>
  </parserConfiguration>
  <parserConfiguration>
    <parser>markdownc</parser>
    <patterns>
      <pattern>*{*}/apt/{*}*</pattern>
    </patterns>
  </parserConfiguration>
<parserConfigurations>

[jira-importer]

Konrad Windszus commented

I think the most flexible way is to introduce a configuration field leveraging PlexusConfiguration and https://github.com/eclipse/sisu.plexus/blob/master/org.eclipse.sisu.plexus/src/main/java/org/codehaus/plexus/component/configurator/ComponentConfigurator.java (similar to what Maven does internally in https://github.com/apache/maven/blob/267de063eec17111688fd1a27d4e3aae6c8d0c51/maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java#L717). That way the actual parameter names depend on the underlying parser and the injection would work the same as for Mojo parameters.
This would just require doxia-site-tools to allow to pass a callback in the format Consumer<Parser> parserConfigurator.

Within the mojo one can use an injected MojoExecution and retrieve the configurator and class realm from its MojoDescriptor.

[jira-importer]

Michael Osipov commented

Good idea, similar to the Maven Release Plugin.