May I add, based from the currently deployed site, the first page you
get after clicking the plugin name, is
Project Info -> About
which is a replica of the page
Project Reports -> Plugin documentation
just fyi
Pete Marvin King wrote:
I think it's a good idea to be able to pull out the Project Document
to the top-level menus.
Currently it's hidden under Project Reports. The usual way to include
it on the site
descriptor is through ${reports}, maybe Project Documentation can have
its own
"macro definition?" like ${generated_documentation}. Or there's
already one and didn't
know about it. =)
Do you think it's also a good idea to standardized the top-level
menus? Pages no matter
how good is useless if it's not visible or tend to be ignored if not
easily accessible.
pete marvin
Brett Porter wrote:
I agree, I think there are some lessons to be learned from this for
apis and other project types in general (archetypes, and so on), and
the same tools can be used.
Worth keeping in mind, but I believe we've identified a particular
problem with plugin docs and should work to improve that asap.
- Brett
On 20/06/2006 1:15 AM, Ruel Loehr wrote:
Why stop at a plugin? Wouldn't this be valuable to have for
thirdparty dependencies as well?
Ruel Loehr
JBoss QA
-----------------------------
512-342-7840 ext 2011
Yahoo: ruelloehr
Skype: ruelloehr
AOL: dokoruel
-----Original Message-----
From: Jason van Zyl [mailto:[EMAIL PROTECTED] Sent: Monday, June 19,
2006 9:56 AM
To: Maven Developers List
Subject: Re: Plugin documentation standard
On 19 Jun 06, at 9:47 AM 19 Jun 06, Brett Porter wrote:
Hi,
Just thought I'd break this one out. This needs to be converted to
a guide - which is one of the tasks I'll list at the end.
(this is MNG-1987, btw)
* Required POM Elements
- modelVersion, version, group ID, artifact ID, packaging (required
anyway to build)
- name
- description
- url
- issueManagement
- prerequisites > maven (I think it's good to make people think
about this)
- inceptionYear
- mailingLists (just a warning if missing as I guess there might
not be one, though we should have some other contact details - do
general contact details fit a "list" description?)
- license
- scm (warning if missing, may not be OSS!)
- organization
- plugin report must be configured
* Plugin configuration
- each @parameter field must have a description. Not required if
@readonly or @component
- Class level should have a description.
* Documents
- plugins must have an /index.html (from apt, xdoc, html etc). Not
generated automatically
- plugins must have a /usage.html, where the standard use case is
described. The recommended lifecycle phases should be listed. This
will almost be boilerplate (just some common configuration items,
how to include it in the POM, and whether it usually needs
executions or not). It will probably repeat for each goal available.
- plugins should have examples/*.html for individual use cases.
- plugins should have a FAQ page for common questions, issues, and
misunderstandings
Consider this example:
- use case: http://maven.apache.org/plugins/maven-release-plugin/
introduction.html
- specific examples: http://maven.apache.org/plugins/maven-release-
plugin/howto.html (should be broken out into examples/dryRun.apt, etc)
* Site descriptor
- navigation must include the link to the usage and the examples
under that
* Reports
- Plugin must have javadoc, jxr and changelog reports
* General guidelines
- Always be able to publish the latest and greatest. Mark new
features with the version they were introduced. Mark caveats in
certain versions.
- The Jetty6 and Cargo plugins are the level of information we are
looking for.
* Tasks (any volunteers? If so, please create a JIRA and grab it
(and drop a reply here to say so - eventually we'll get these all
in regardless though)
- convert the above to a guide on the Maven website
- add any missing checks to the docck plugin
- wire up the docck plugin to all maven plugins
- pilot plugins. Some of these have gone into JIRA already and been
assigned.
- rework the plugin reference page (a separate discussion,
MPLUGIN-7 is a starting point). This should be reworked not to
overwrite index.html
- create an archetype for a compliant plugin
- add @since tag to plugin fields (it's standard javadoc so we can
dual purpose it, but we need to acknowledge it in the descriptor)
Any additional thoughts?
Make a plugin to check all these thing and plug it into the
validation phase. This is all nice to enumerate but it will only
take effect when it is easy for people to comply.
- Brett
--
Brett Porter <[EMAIL PROTECTED]>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Jason van Zyl
[EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
