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.

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

[michalvavrik]

cc @machi1990 @gsmet

[michalvavrik]

Failing tests are not related.

[michalvavrik]

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

[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.

[gsmet]

@michalvavrik I force pushed a rebase and an additional commit (so make sure to pull the branch before making other changes).

Overall it looks good and is useful but I have a doubt about the presence of the environment variables such as Environment variable: BOMARTIFACTID. My guess is that this shouldn't be there and it's just some noise coming from the config stuff.

Could you have a look?

[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]

Failing Jobs - Building dba1b1e

Status	Name	Step	Failures	Logs	Raw logs
✔️	Maven Tests - JDK 11
⌛	Maven Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

⚙️ Maven Tests - JDK 11 Windows #

📦 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

[gsmet]

Let's get this in. Thanks!

Addressed