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]
