Generate Quarkus Maven Plugin Config Docs

[michalvavrik]

partially resolves: #1204

I used Quarkus Maven Plugin descriptor to generate list of goals, their parameters and default values to one config file, and list of compile and runtime dependencies to second config file. I also created quarkus-maven-plugin.adoc, to make it clear how could newly generated files be used.

If you are building docs as usual (e.g. mvn -DquicklyDocs), QuarkusMavenPluginDocsGenerator will pick up plugin.xml and extract required information. I also adjusted JavaDocParser in a way that we strip starting space of the HTML text node after new line as it leads to a literal block. I did it mainly because of CreateExtensionMojo, but it makes sense in general to prevent this literal block as author of JavaDoc with HTML certainly didn't mean to create one.

There are some open questions:

• Should we translate ${open-lang-package}, ${noDeps}, etc. and how?
• Required flag is not very useful here as org.apache.maven.plugins.annotations.Parameter#required is used by the Quarkus Maven plugin authors AFAIK, instead information that parameter is required is usually mentioned in JavaDoc.
• I added manually some extra space to quarkus-maven-plugin.adoc as when there is long table of contents followed be parameters table, it caused ugly gap between quarkus:add-extension description and the table of its parameters. I think it's possible to find more responsive solution in quarkusio.github.io and the issue can't be addressed here.

You can find generated "QUARKUS MAVEN PLUGIN" docs here: quarkus-mvn-plugin-page.zip

[michalvavrik]

cc @machi1990 @gsmet

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building a4504ffac49a991ab77e87ef9fbd8834cced0b2b

Status	Name	Step	Failures	Logs	Raw logs
:heavy_check_mark:	JVM Tests - JDK 11
✖	JVM Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 17	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

:gear: JVM Tests - JDK 11 Windows #

- Failing: extensions/smallrye-reactive-messaging-amqp/deployment 
! Skipped: integration-tests/reactive-messaging-amqp 

:package: extensions/smallrye-reactive-messaging-amqp/deployment

✖ io.quarkus.smallrye.reactivemessaging.amqp.AnonymousAmqpTest.test line 30 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with io.quarkus.smallrye.reactivemessaging.amqp.AnonymousAmqpTest was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

---

:gear: JVM Tests - JDK 17 #

- Failing: integration-tests/smallrye-context-propagation 

:package: integration-tests/smallrye-context-propagation

✖ io.quarkus.context.test.mutiny.MutinyContextPropagationTest.testTransactionPropagationWithUniCreatedFromCS line 120 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

[michalvavrik]

Failing tests are not related.

[michalvavrik]

Is there ETA for the review, please? @ebullient @gsmet @FroMage

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building d1b0b9549f752f431c8656d29efe01b4cde30f59

Status	Name	Step	Failures	Logs	Raw logs
:heavy_check_mark:	Maven Tests - JDK 11
:hourglass:	Maven Tests - JDK 11 Windows	Build	:warning: Check →	Logs	Raw logs

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building a61b8e8fafb5f5679e0c4e4cf3005f4824ef0bec

Status	Name	Step	Failures	Logs	Raw logs
:heavy_check_mark:	JVM Tests - JDK 11
✖	JVM Tests - JDK 11 Windows	Build	:warning: Check →	Logs	Raw logs
:heavy_check_mark:	JVM Tests - JDK 17
:heavy_check_mark:	JVM Tests - JDK 18

[FroMage]

Hi, this looks very useful, thanks!

I tried generating the docs, but didn't see any TOC, is it normal? Also, why are we listing the plugin dependencies, is it useful?

[michalvavrik]

thank you @FroMage

• table of contents is only added in quarkusio.github.io https://github.com/quarkusio/quarkusio.github.io/blob/3c4c90c87eee46cb8c5de86f52cecf5f5a35be28/_layouts/guides.html; no other guide has it. I'm not happy about the workaround for TOC (extra gaps), but the problem does not exists for other guides as they either has longer description or shorter TOC. I'll file an issue in quarkusio.github.io if this get merged.
• I doubt it's very useful to list plugin dependencies (except for rare cases), but Maven website list deps for their plugins (please see Surefire deps) and so does MojoHaus (f.e. Build Helper). As the dependency list is at the end, you can simply not scroll there?

[FroMage]

OK, I understand about the TOC, thanks.

I doubt it's very useful to list plugin dependencies (except for rare cases), but Maven website list deps for their plugins (please see Surefire deps) and so does MojoHaus (f.e. Build Helper). As the dependency list is at the end, you can simply not scroll there?

It's not because we have room on a page that we should put stuff that's not useful ;) Unless anyone can say they want it, let's just remove it.

[michalvavrik]

Sure, I'll remove it.

[michalvavrik]

I dropped the dependency list.

[michalvavrik]

@gsmet @ebullient @FroMage if it is possible, please give me a hint what's the ETA for the review (it has been almost a month and half). Maybe there is something I can do? Like, if this is not preferable solution, I can rewrite it etc. However if you simply don't have a time, I understand and please ignore this comment. Thank you

[michalvavrik]

I updated attached zip (even though you will probably run quarkus.github.io locally) in case you want to see the changes. Thank you for the feedback.

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building 0ee00005d63e906ed2d62583fb940478b27962a2

Status	Name	Step	Failures	Logs	Raw logs
✖	Gradle Tests - JDK 11	Build	Failures	Logs	Raw logs
:heavy_check_mark:	Gradle Tests - JDK 11 Windows

Full information is available in the Build summary check run.

Failures

:gear: Gradle Tests - JDK 11 #

- Failing: integration-tests/gradle 

:package: integration-tests/gradle

✖ io.quarkus.gradle.devmode.CompositeBuildWithDependenciesDevModeTest.main line 24 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with lambda expression in io.quarkus.test.devmode.util.DevModeTestUtils that uses java.util.function.Supplier, java.util.function.Supplierjava.util.concurrent.atomic.AtomicReference, java.util.concurrent.atomic.AtomicReferencejava.lang.String, java.lang.Stringboolean was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

[michalvavrik]

Sure, I'll have a look @gsmet . Thanks

[michalvavrik]

You're right @gsmet , it didn't make sense to show env vars there, fixed. I also squashed commits to have one per PR.

[quarkus-bot[bot]]

Failing Jobs - Building dba1b1efdd75043e82c084ee5d08df530c848d46

Status	Name	Step	Failures	Logs	Raw logs
:heavy_check_mark:	Maven Tests - JDK 11
:hourglass:	Maven Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

:gear: Maven Tests - JDK 11 Windows #

:package: integration-tests/maven

✖ io.quarkus.maven.it.JarRunnerIT.testThatLegacyJarFormatWorks line 204 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with lambda expression in io.quarkus.maven.it.JarRunnerIT that uses io.quarkus.maven.it.verifier.MavenProcessInvocationResult was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

✖ io.quarkus.maven.it.JarRunnerIT.testThatLegacyJarFormatWorks line 204 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with lambda expression in io.quarkus.maven.it.JarRunnerIT that uses io.quarkus.maven.it.verifier.MavenProcessInvocationResult was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

[michalvavrik]

JarRunnerIT.testThatLegacyJarFormatWorks failure not related