Reformat the autogenerated goal parameters page to improve readibility.

Currently this plugin generates an xdoc file describing the goals and parameters of the plugin.
Shouldn't be instead of generating an xdoc, we generate an HTML report??
Currently it generates html report about the goal but not about the parameter.

yes, it should be direct to HTML eventually.

I tried to rewrite PluginXdocGenerator as a MavenReport, but I could not figure out how to use AbstractMavenMultiPageReport : did not find any documentation nor report using it.

Now I have code to write the new HTML report as a unique page : overview + 1 section per goal

If I don't find how to break it into multiple pages, I'll publish this version here : it's better than nothing and I hope it will help

Hervé,

FYI plugin:xdoc is already implemented as a MavenReport, according the MNG-706 issue
http://svn.apache.org/viewcvs.cgi?rev=291309&view=rev
http://maven.apache.org/plugins/maven-plugin-plugin/report-mojo.html

Here is a small thread about AbstractMavenMultiPageReport subject:
http://www.nabble.com/multi-page-reports-t690194.html#a1915556

HTH

Thanks a lot for your support.

Hi Vincent,

Sorry, I did not explain myself clearly : I'm new to Maven2 internals (which are huge, but great)...

What I'm trying to do is to replace xdoc gerenation (what is done currently) by direct HTML generation through Sink API (what is proposed by Johnny and Brett on previous comments).
To do that, I need a way to create multiple pages with Sink API.
AbstractMultiPageReport has startPage(outputName) and endPage(MultiPageSink) methods : that seems to be here just for this need.
But when I call startPage, I get a NPE...

I could not find any Report using this API : when multi-page is needed, everybody seems to go back to xdoc generation (that's the "solution" proposed in the thread you quote).

Do you know how this class works ?

Thank for your interest and help

Hervé,

How was your work here? any progress?

Anyway, the suggestion is to make the page more like the page in maven's project descriptor... where the items are listed on a section and the their details are tabled somewhere below it. And I don't think that you'll need to use the Multipage report for that as they're in one page.

I would like to work on this right now, but when I imagine a page with plugin parameters listed and their detail table below, I feel like I only made it uglier. Is that really what we want this page to look like ?

Edwin,

I did not work more on this issue : I was waiting for patches on MPLUGIN-11 to be applied, because this issue consists to modify PluginXdocGenerator.java after them.

Now, the big question is "what do we want this page to look like ?".
I totally agree with you : the first idea proposed in the issue does not IMHO improve the report.

I had other ideas : here are 2 pages I wrote to check how it would look like. What do you think of these ?

Those pages are alright... but I was thinking of something similar to javadoc's Field Summary/Field Details section.

But if the plugin have the javadoc report included, they might become too similar.

Currently, the class generating the report (PluginXdocGenerator.java) is not in the proper component and package (org.apache.maven.tools.plugin.generator instead of org.apache.maven.plugin.plugin).
It must be moved as proposed in MPLUGIN-11. Then, we'll be able to modify it: there are many good ideas how the report could be improved.

Current PluginXdocGenerator.java generates multiple report pages : if we want to rewrite it with Sink API instead of xdoc, we'll need the ability to have multi-page reports as requested in MNG-2410.

Perhaps this issue should be split in 2 :
1. reformat the page (staying with xdoc)
2. rewrite the report with Sink API

I'm attaching my proposed html, and patch to produce it.

Hervé, do you have patches to your proposed pages? Please attach them so the maven dev team can choose what they want.... or maybe suggest something else.

we will need to do this without the multi-page feature for now.

Edwin - that latest page looks good, however

• I'd avoid using tables in the lower section and I'd include the description again (more like Javadoc).
• Instead of Optional? Yes I'd say "Required: Yes/No".
• In the table at the top, I think since the type is short I'd put it in it's own column which will make it more compact.
• I'd suggest splitting the top table into 2 tables: first, "required fields" and "optional fields"

Brett, please see attached sample page if that's what you like.

Please disregard my previous attachements... in this one, i've removed the read-only and plexus component/injected parameters.

Edwin,

Thank you for your interest in my patches : but your proposal is a lot better.
You can ignore mine with no regret, and apply your patch ASAP.

I re-did my patch to allow the @since tag to be shown in the report.

applied, but please make the following modifications:

• remove the empty <p/> tag between the name and description.
• don't show the optional parameters section if there aren't any (likewise the required parameters)
• make optional, required, and parameter details headings h3 instead of h2

Other features that have been request:

• show class level metadata at the top
• show default value at the end of the description if there is one

Brett,

Please see attached sample for the revisions/new features requested. I've also attached the patch to produce it.