Support for Apache Maven Site Plugin Version 4.0.0-MX

[markusschaefer]

What is this issue about?

• Bug report
• Feature request
• Question

Description
The latest version of the asciidoctor-maven-plugin ist not compatible with the new released version 4.0.0-M1 of the maven-site-plugin.
The maven-site-plugin updated to doxia 2.0.0-M2 (see https://blogs.apache.org/maven/entry/apache-maven-site-plugin-version5)
The asciidoctor-maven-plugin is still on doxia version 1.10

At runtime the asciidoctor-maven-plugin gets injected the higher doxia version. Unfortunately the constructor of AbstractParserModule has been deleted (see apache/maven-doxia@8e689f8)

[WARNING] Error injecting: org.asciidoctor.maven.site.AsciidoctorDoxiaParserModule
com.google.inject.ProvisionException: Unable to provision, see the following errors:

1. Error injecting constructor, java.lang.NoSuchMethodError: 'void org.apache.maven.doxia.parser.module.AbstractParserModule.(java.lang.String, java.lang.String, java.lang.String)'
   at org.asciidoctor.maven.site.AsciidoctorDoxiaParserModule.(Unknown Source)
   while locating org.asciidoctor.maven.site.AsciidoctorDoxiaParserModule

Environment information

• asciidoctor-maven-plugin version: 2.2.2
• asciidoctorj version: ___

• Maven: 3.8.5
• Java: 11.0.12
• OS version: windows 10

[abelsromero]

Thanks for the heads up and specially for the hint. It took me a good time to find the upgrade was not working because of the constructor, fun fact it actually still exists, but arguments order was changed 🤦‍♂️

I have a working POC so we can merge soon, but can't make promises about release, but in case of need, we can make a "RC".

[markusschaefer]

Thanks for the fast reaction. Actually I can wait for the regular release.

[abelsromero]

Reopen for #589 (comment).

• In regards of the milestone will see what comes first, but this is not blocking for our v3.x.
• Current site v4.x.x compatibility tests are in branch https://github.com/asciidoctor/asciidoctor-maven-plugin/tree/issue-578-experimental-maven-site-4.x.x, will be aligning with main.

[michael-o]

I highly recommend to apply/keep everything which is compatible with Doxia 1.x and MSITE 3.x. This will make transition easier. I have done the same for our plugins.

[jdimeo]

Very eager for this since I was previously using Markdown but now I want to integrate CLI manpages generated as ADoc by Picocli and I can't downgrade my site plugin version. thanks!

[abelsromero]

Thanks @jdimeo!
The experimental branch has been updated to the latest maven-site 4.0.0-M8 and tests pass.
If anyone wants to test it:

1. Build it locally (mvn install)
2. Update module name: the current plugin has been ported to a separate module, details are in the documentation https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/issue-578-experimental-maven-site-4.x.x/docs/modules/site-integration/pages/v3-migration-guide.adoc

[abelsromero]

As OSS, there's no release date on the horizon. I personally would like to see AsciidoctorJ v3 out first, then release maven-plugin and site modules with it.

[michael-o]

Re: main...issue-578-experimental-maven-site-4.x.x#diff-3e535c133a8f6684fe6a1a394f5c1be64bae5861bde1d1602167e73c423d9ae6R12

Don't use with Doxia 2.0.0 stack, it does not proper cover all needs. Use 2.0.0-Mx.

[abelsromero]

Don't use with Doxia 2.0.0 stack, it does not proper cover all needs. Use 2.0.0-Mx.

Thanks a lot! These are the kind of things that are hard to grasp. There's no bom right ?

[michael-o]

I recommend to follow: https://cwiki.apache.org/confluence/display/MAVEN/Towards+Doxia+2.0.0+Stack

[jdimeo]

Uh oh. I hit https://issues.apache.org/jira/browse/MSITE-849 on a normal mvn site (not mvn site:run as mentioned in the issue).

I used https://jitpack.io to pull in this branch:

<plugin>
	<artifactId>maven-site-plugin</artifactId>
	<executions>
		<execution>
			<id>pre-site-dry-run</id>
			<goals><goal>site</goal></goals>
			<phase>pre-site</phase>
		</execution>
	</executions>
	<dependencies>
		<dependency>
		    <groupId>com.github.abelsromero.asciidoctor-maven-plugin</groupId>
		    <artifactId>asciidoctor-converter-doxia-module</artifactId>
		    <version>issue-578-experimental-maven-site-4.x.x-SNAPSHOT</version>
		</dependency>
	</dependencies>
</plugin>

(I'm also using a forked site plugin that uses multiple CPU cores to render, which you can see why at over 80k files :-) )

[jdimeo]

@abelsromero I was able to get your fork working with M13 (https://github.com/abelsromero/asciidoctor-maven-plugin/tree/issue-578-experimental-maven-site-4.x.x), but only by downgrading to Java 8 or else the dependency is "banned". Then I had to bypass injection and manually provide the Doxia parser implementation inside the plugin. Very very ugly, but it works now! Edit: apparently the ASCIIDoc rendered by the Picocli generator isn't working completely...

There is much more in the source:

Eagerly awaiting formal releases of all of this - thank you all for your efforts.

[jdimeo]

OK I finally got it to really work by merging the tip of the plugin with your branch (plus reverting to Java 8 and directly including it into the site plugin rather than relying on injection).

[abelsromero]

Eagerly awaiting formal releases of all of this - thank you all for your efforts.

This is an experimental branch to test Maven v4 in advance. It's more of an exercise, until Maven 4 stable is out this will remain as such. And currently is still alpha.

What is the actual problem you are trying to solve @jdimeo ? You mentioned picocli and Java 8 but I don't understand what is the end goal is?

[jdimeo]

I need ASCII doctor to work with the 4.x.x version of the site plugin. I have forked the site plugin to support parallel rendering to HTML and had to hack it to make it truly thread safe. I have over 100,000 markdown and adoc files in my site and I use 12 CPU cores in the CI/CD job to do parallel work. So I need the M13 site plugin, newest Doxia, etc. to work with ASCII doctor.

I had to revert to Java 8 otherwise ASCII doctor was "banned" as a dependency from site plugin by the enforcer plugin.

[abelsromero]

I have over 100,000 markdown and adoc files in my site

That's an interesting use case, have you tried initializing the Asciidoctor instance ( Asciidoctor.Factory.create()) as a static attribute? I never invested time looking into performance and focused on ensuring it works, but ti should be fine and reduce time considerably.

I had to revert to Java 8 otherwise ASCII doctor was "banned" as a dependency from site plugin by the enforcer plugin.

Not sure what enforcer you mean. The experimental branch works fine in CI which runs Java from 11 to 21.

If it helps I've been thinking of moving experimental branches to this git repo. That way they'll get dependabot bumps when new versions are available and we'd make sure they are in shape. Not it depends more on having some outside reminder to take a look at them and rebase.

[jdimeo]

Not sure what enforcer you mean.

I mean on the maven-site-plugin side: the maven-enforcer-plugin is now rejecting ASCII Doctor and thus failing to inject the Doxia parser because it's on Java 11. So I had to bring it back to 8 only for maven-site-plugin, not because of any fault of ASCII doctor!

the 100k files are Markdown, not adoc. Those are only a couple dozen as documentation for our CLI! so performance is no issue, but it's enough to where I had to parallelize the overall site plugin: https://github.com/jdimeo/maven-site-plugin/blob/master/src/main/java/org/apache/maven/plugins/site/render/SiteMojo.java#L249
It's super nasty which is why I haven't opened a PR. It's totally necessary for my use case but not ready for prime time.

[abelsromero]

Thanks for the clarification.

I updated the experimental branch with the latest changes btw, and regarding...

not ready for prime time.

Nothing ever is trully. I'd suggest approaching the team and discuss with them. Things make take time but I am sure it's an interesting idea, they'll like to discuss, especially if there's already some code to review. I'd start mentioning in the "Maven User" mailing list https://maven.apache.org/plugins/maven-site-plugin/mailing-lists.html.