Filtering Javadoc overview.html and package.html

[Andrew Hughes <ah...@gmail.com>]

Hello All,

I am trying to filter the overview.html and package.html javadoc resources.
Specifically, it is worthwhile inserting the ${project.description} and ${
project.version} and maybe even some other information like the SCM, Issue
Tracking, information within the Javadocs. I have selected the non-default
location for these files within the src/main/java location. Why, because if
someone renames a package/directory... then the code and doco diverge. The
filter below does not work, but it does work if I apply this to the
src/main/resources directory.

How do I filter the Javadoc files when generating the javadocs?

  <build>
    <resources>
      <resource>
        <directory>src/main/java</directory>
        <filtering>true</filtering>
        <includes>
            <include>**/*.html</include>
        </includes>
      </resource>
    </resources>
  </build>

Much Appreciated!!!

Andrew

Re: Filtering Javadoc overview.html and package.html

[Andrew Hughes <ah...@gmail.com>]

Thanks Stephen!!!

This sounds like a lot of work.... and your description is right on the
money... so thank you very much!

I would prefer not to deviate too much from the maven default behaviour...
so this one I might have to let slip.

But thanks very much for taking the time to provide such a concise response.

Much Appreciated

--Andrew


On Wed, Mar 12, 2008 at 7:29 PM, Stephen Connolly <
stephen.alan.connolly@gmail.com> wrote:

> You need to have the filtering bound to the generate-sources phase of the
> build lifecycle. AFAIK filtering is bound to a phase after the phase that
> javadoc requires, so it will not get invoked.
>
> I would put your javadocs in a third folder: src/main/javadoc
>
> I would bind an additional execution of the resources plugin to the
> generate-sources phase that copies and filters the javadocs from
> src/main/javadoc to target/generated-sources/javadoc
>
> And finally I would bind an execution of the buildhelper-maven-plugin (at
> mojo.codehaus.org) to the generate-sources phase as well that adds
> target/generated-sources/javadoc as an additional source path.
>
> This will result in the filtering of (only) the javadocs occurring during
> the generate-sources phase as well as defining the filtered javdocs as
> being
> source code.  When the javadoc plugin runs it looks for these files in the
> defined source directories (which is what the buildhelper plugin will be
> adding)
>
> -Stephen
>
> On Wed, Mar 12, 2008 at 1:50 AM, Andrew Hughes <ah...@gmail.com> wrote:
>
> > Hello All,
> >
> > I am trying to filter the overview.html and package.html javadoc
> > resources.
> > Specifically, it is worthwhile inserting the ${project.description} and
> ${
> > project.version} and maybe even some other information like the SCM,
> Issue
> > Tracking, information within the Javadocs. I have selected the
> non-default
> > location for these files within the src/main/java location. Why, because
> > if
> > someone renames a package/directory... then the code and doco diverge.
> The
> > filter below does not work, but it does work if I apply this to the
> > src/main/resources directory.
> >
> > How do I filter the Javadoc files when generating the javadocs?
> >
> >  <build>
> >    <resources>
> >      <resource>
> >        <directory>src/main/java</directory>
> >        <filtering>true</filtering>
> >        <includes>
> >            <include>**/*.html</include>
> >        </includes>
> >      </resource>
> >    </resources>
> >  </build>
> >
> > Much Appreciated!!!
> >
> > Andrew
> >
>

Re: Filtering Javadoc overview.html and package.html

[Stephen Connolly <st...@gmail.com>]

You need to have the filtering bound to the generate-sources phase of the
build lifecycle. AFAIK filtering is bound to a phase after the phase that
javadoc requires, so it will not get invoked.

I would put your javadocs in a third folder: src/main/javadoc

I would bind an additional execution of the resources plugin to the
generate-sources phase that copies and filters the javadocs from
src/main/javadoc to target/generated-sources/javadoc

And finally I would bind an execution of the buildhelper-maven-plugin (at
mojo.codehaus.org) to the generate-sources phase as well that adds
target/generated-sources/javadoc as an additional source path.

This will result in the filtering of (only) the javadocs occurring during
the generate-sources phase as well as defining the filtered javdocs as being
source code.  When the javadoc plugin runs it looks for these files in the
defined source directories (which is what the buildhelper plugin will be
adding)

-Stephen

On Wed, Mar 12, 2008 at 1:50 AM, Andrew Hughes <ah...@gmail.com> wrote:

> Hello All,
>
> I am trying to filter the overview.html and package.html javadoc
> resources.
> Specifically, it is worthwhile inserting the ${project.description} and ${
> project.version} and maybe even some other information like the SCM, Issue
> Tracking, information within the Javadocs. I have selected the non-default
> location for these files within the src/main/java location. Why, because
> if
> someone renames a package/directory... then the code and doco diverge. The
> filter below does not work, but it does work if I apply this to the
> src/main/resources directory.
>
> How do I filter the Javadoc files when generating the javadocs?
>
>  <build>
>    <resources>
>      <resource>
>        <directory>src/main/java</directory>
>        <filtering>true</filtering>
>        <includes>
>            <include>**/*.html</include>
>        </includes>
>      </resource>
>    </resources>
>  </build>
>
> Much Appreciated!!!
>
> Andrew
>