Difference between revisions of "Maven project site guide"

From MPDLMediaWiki
Jump to navigation Jump to search
(New page: == Create a custom page ==)
 
m
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Maven creates most of its site content on it's own. This behavior is controlled by reporting plugins.
== Reporting plugins ==
These reporting plugins are defined in
the ''parent pom'' of each project.
Here you can see a sample report entry for the javadoc documentation:
<pre>
<reporting>
        <plugins>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
</plugin>
...
</pre>
This simple entry in the ''pom'' creates the whole documentation page and automatically links it in the root project page. If you want to have a new reporting feature, just add
the module in the ''parent pom'' and every submodule will derive from it.
If you want to add a custom page to the generated ones, this can easily be done.
== Create a custom page ==
== Create a custom page ==
The source code of the html files are kept in the svn repository together with the other resources (java src.) of the project.
So if you want add a page you have to checkout the source files of the project. An explanation to get the sources and to get maven can be found in the [[Installation of maven]] guide.
In every project you can see the following directory structure:
<pre>
  +- src/
  +- site/
      +- apt/
      |  +- index.apt
      |
      +- xdoc/
      |  +- other.xml
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- site.xml
</pre>
You can see the site descriptor ''site.xml'' and all the custom pages separated by the supported doc formats. These are:
* ''apt'' ("Almost plain text") is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. Reference lies [http://maven.apache.org/doxia/references/apt-format.html here].
* ''xdoc'' is a xml documentation system, defined by maven. The reference can be found [http://maven.apache.org/guides/mini/guide-site.html here].
* ''fml'' is mainly used for creating FAQs. An example is [http://www.javaworld.com/javaworld/jw-02-2006/jw-0227-maven.html?page=4 here]
The site descriptor defines how the created pages are included in the project page. A good HowTo on defining a site descriptor and can be found [http://maven.apache.org/guides/mini/guide-site.html here]
So for creating a page, you would
* first create the page in the desired format
<pre>
+- site/
      +- xdoc/
      |  +- new_folder/
            +- new_page.xml
</pre>
* and then define it in the site descriptor ''site.xml''
<pre>
<menu name="Sample menu">
      <item name="Sample page" href="new_folder/new_page.html"/>
    </menu>
</pre>
[[Category:ESciDoc]]
[[Category:How To]]

Latest revision as of 13:19, 5 January 2011

Maven creates most of its site content on it's own. This behavior is controlled by reporting plugins.

Reporting plugins

These reporting plugins are defined in the parent pom of each project.

Here you can see a sample report entry for the javadoc documentation:

<reporting>
        <plugins>
		<plugin>
			<artifactId>maven-javadoc-plugin</artifactId>
		</plugin>
	...

This simple entry in the pom creates the whole documentation page and automatically links it in the root project page. If you want to have a new reporting feature, just add the module in the parent pom and every submodule will derive from it.

If you want to add a custom page to the generated ones, this can easily be done.

Create a custom page

The source code of the html files are kept in the svn repository together with the other resources (java src.) of the project. So if you want add a page you have to checkout the source files of the project. An explanation to get the sources and to get maven can be found in the Installation of maven guide.

In every project you can see the following directory structure:

   +- src/
   +- site/
      +- apt/
      |  +- index.apt
      |
      +- xdoc/
      |  +- other.xml
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- site.xml

You can see the site descriptor site.xml and all the custom pages separated by the supported doc formats. These are:

  • apt ("Almost plain text") is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. Reference lies here.
  • xdoc is a xml documentation system, defined by maven. The reference can be found here.
  • fml is mainly used for creating FAQs. An example is here

The site descriptor defines how the created pages are included in the project page. A good HowTo on defining a site descriptor and can be found here

So for creating a page, you would

  • first create the page in the desired format
+- site/
      +- xdoc/
      |  +- new_folder/
             +- new_page.xml
  • and then define it in the site descriptor site.xml
 <menu name="Sample menu">
      <item name="Sample page" href="new_folder/new_page.html"/>
    </menu>