You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/03/04 06:56:25 UTC
svn commit: r156134 - maven/maven-1/core/trunk/xdocs/using/site.xml
Author: brett
Date: Thu Mar 3 21:56:22 2005
New Revision: 156134
URL: http://svn.apache.org/viewcvs?view=rev&rev=156134
Log:
site instructions
Modified:
maven/maven-1/core/trunk/xdocs/using/site.xml
Modified: maven/maven-1/core/trunk/xdocs/using/site.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/site.xml?view=diff&r1=156133&r2=156134
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/site.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/site.xml Thu Mar 3 21:56:22 2005
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!--
/*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -17,136 +17,77 @@
*/
-->
-
<document>
<properties>
<title>Site Navigation</title>
<author email="bwalding@apache.org">Ben Walding</author>
+ <author email="brett@apache.org">Brett Porter</author>
</properties>
<body>
-<!-- TODO: flesh this out with a full walk through (visual walkthrough of maven site)
- TODO: talk about generated docs - in particular have already referenced cvs-usage from scm.xml
- <section name="Site Generation">
- <p>
- Maven can be used to generate an entire web site for your
- project. This web site will contain various reports generated
- by the numerous plugins included in Maven such as javadocs,
- metrics, unit test results, changelogs, and many more. The rest
- of this section talks about the various site customization
- options available in Maven.
- </p>
- <subsection name="Colors">
- <p>
- By default, all Maven-generated sites use the same look and
- feel for consistency. This enables users to easily recognize
- a Maven-generated site and immediately feel comfortable
- searching for information on the site. Of course, the Maven
- development team understands that users might want to
- customize their own sites. The easiest method to alter the
- appearance of the Maven-generated site is to specify your own
- color scheme to use. This is as simple as setting the
- appropriate properties in your project's
- <code>project.properties</code> file. All of the available
- properties are described in the <a
- href="plugins/xdoc/properties.html">xdoc plugin</a>.
- </p>
- </subsection>
- <subsection name="Stylesheets">
- <p>
- If you feel that colors are simply not enough to distinguish
- your site, you can specify your own stylesheet that will be
- used. To override the Maven-supplied stylesheet, copy your
- own and override the <code>maven.css</code> stylesheet in your
- <code>${basedir}/xdocs/stylesheets/</code> directory. You can
- also specify your own javadoc stylesheet by setting the
- <code>maven.javadoc.stylesheet</code> property.
- </p>
- </subsection>
- <subsection name="Reports">
+ <section name="Site Generation">
<p>
- Finally, if you want to customize which reports are
- automatically generated for your site, you need to include the
- <a href="project-descriptor.html#reports"><code>reports</code></a> tag
- in your project descriptor. As of this writing, if you do not
- utilize the <code>reports</code> tag, all of the plugin
- reports will be generated. This tag enables you to
- selectively choose which reports to include and exclude as
- well as the order of the reports.
+ Maven can be used to generate an entire web site for your project. The web site can be used to house all of
+ your user-facing documentation, generated as flat HTML with a common look and feel.
</p>
<p>
- The <code>standard</code> set of reports is currently hard coded into
- the <code>xdoc</code> plugin. These are:
+ It also contains a number of generated documents based on the information in your project. This can include
+ SCM information, mailing lists and a list of developers, as well as FAQs and release notes based on
+ additional metadata you provide.
</p>
- <source>
-maven-changelog-plugin
-maven-changes-plugin
-maven-checkstyle-plugin
-maven-developer-activity-plugin
-maven-file-activity-plugin
-maven-javadoc-plugin
-maven-jdepend-plugin
-maven-junit-report-plugin
-maven-jxr-plugin
-maven-license-plugin
-maven-linkcheck-plugin
-maven-pmd-plugin
-maven-tasklist-plugin
- </source>
- <p>If you wish to use the default reports but remove one or add one, the
- preferred method is to use a postGoal for xdoc:register-reports like this:
- </p>
-
- <source><![CDATA[
-<postGoal name="xdoc:register-reports">
- <attainGoal name="maven-changelog-plugin:deregister"/>
- <attainGoal name="maven-myown-plugin:register"/>
-</postGoal>
- ]]></source>
-
- </subsection>
- <subsection name="Exclusion of All Maven-Generated Content">
<p>
- Users building documentation-only sites or sites that
- aggregate a lot of sub-projects might want to prevent the
- inclusion of the entire "Project Documentation" section of the
- navigation bar on their sites. This can be done by setting
- the <code>maven.xdoc.includeProjectDocumentation</code>
- property to the value of <code>no</code>. By default, Maven
- will include the "Project Documentation" section of the
- navigation bar which includes information about the project as
- well as links to the numerous Maven-generated reports.
+ Finally, the web site will contain various reports about your source code generated
+ by the plugins included in Maven such as javadocs, metrics, unit test results, changelogs, and more.
</p>
- </subsection>
-
- </section>
+ </section>
- <section name="Implementation">
- <p>
- Create a single navigation.xml that contains the menu structure for
- the entire document tree. Add all items and sub-items.
- </p>
-
- <p>
- For items that can collapse when you are not browsing them, add <code>collapse="true"</code>
- to the item declaration.
- </p>
-
- <source><![CDATA[
+ <section name="Adding Documents to the Site">
+ <subsection name="Creating a Site Descriptor">
+ <p>
+ To add documents tto the site, first you will need to add them to the navigation so that they can be found.
+ </p>
+ <p>
+ To do this, create a <code>navigation.xml</code> file in the <code>xdocs</code> directory that contains the
+ menu structure for the entire document tree. Add all items and sub-items.
+ </p>
+
+ <p>
+ For items that can collapse when you are not browsing them, add
+ <code>collapse="true"</code>
+ to the item declaration.
+ </p>
+
+ <p>
+ The following is an example <code>navigation.xml</code> file:
+ </p>
+
+ <source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
+
<project name="Maven xdoc Plugin">
+ <!-- Page Title -->
<title>Maven xdoc Plugin</title>
<body>
+
+ <!-- Links defined across the top right of the site -->
<links>
<item name="Maven" href="http://maven.apache.org/"/>
</links>
- <menu>
- <item name="Alpha" href="/alpha/index.html">
+
+ <!-- Menu in the Left Navigation -->
+ <menu name="Menu Name">
+ <!-- Standalone item -->
+ <item name="Item" href="/item.html" />
+
+ <!-- Uncollapsed Submenu -->
+ <item name="Alpha" href="/alpha/index.html">
<item name="Alpha One" href="/alpha/one/index.html"/>
<item name="Alpha Two" href="/alpha/two/index.html"/>
</item>
+
+ <!-- Collapsed Submenu -->
<item name="Beta" href="/beta/index.html" collapse="true">
<item name="Beta One" href="/beta/one/index.html" collapse="true"/>
<item name="Beta Two" href="/beta/two/index.html" collapse="true"/>
@@ -154,60 +95,147 @@
</menu>
</body>
</project>]]></source>
-
- <p>
- Now the menus will expand and collapse as you navigate through them.
- </p>
+ <p>
+ <b>Note: </b> the <code>href</code> element should be absolute, referenced according to your document root
+ (ie, under <code>xdocs</code>).
+ </p>
+ <p>
+ You can also add images to items in the menu, for example:
+ </p>
+ <source><![CDATA[<item name="The Site" href="http://www.thesite.net/" img="http://www.thesite.net/thesite.png"/>]]></source>
+ </subsection>
+ <subsection name="Creating a new Document">
+ <p>
+ The XDoc format is quite simple, and is based on the original Anakia format that originated in Jakarta.
+ The following is a sample XDoc document:
+ </p>
+ <source><![CDATA[
+<document>
+ <properties>
+ <author email="user@company.com">John Doe</author>
+ <title>Page Title</title>
+ </properties>
+ <!-- Optional HEAD element, which is copied as is into the XHTML <head> element -->
+ <head>
+ <meta ... />
+ </head>
+ <body>
+ <!-- The body of the document contains a number of sections -->
+ <section name="section 1">
+
+ <!-- Within sections, any XHTML can be used -->
+ <p>Hi!</p>
+
+ <!-- in addition to XHTML, any number of subsections can be within a section -->
+ <subsection name="subsection 1">
+ <p>Subsection!</p>
+ </subsection>
</section>
-
- <section name="Caveats">
- <ol>
- <li>
- You must refer to subdirectories as /folder/index.html. Navigation will get quite confused
- if you refer to them as /folder/ or just /folder
- </li>
- <li>
- If you have a sub-item with the same url as another item, the site navigation will
- expand to display all items with that URL (when either is selected). All instances
- of the item will be highlighted.
- </li>
- </ol>
+
+ <section name="other section">
+
+ <!-- You can also include preformatted source blocks in the document -->
+ <source>
+code line 1
+code line 2
+ </source>
</section>
+ </body>
+</document>]]></source>
+ <p>
+ To create one of these documents, create an XML file in the directory structure you want for your site under
+ the <code>xdocs</code> document root. For example, <code>/start/introduction.xml</code> will be generated as
+ <code>/start/introduction.html</code> on the final site.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Site Appearance">
+ <p>
+ The following sections give some details on specific customisations you might want to make to the generated site.
+ </p>
+ <p>
+ For more information on customising the generated site, see the <a href="../reference/xdoc/">XDoc plugin reference</a>.
+ </p>
+ <subsection name="Creating Your Own Index Page">
+ <p>
+ Maven will generate a default <code>index.html</code> page for your project based on the
+ <code>description</code> element in the POM. However, this is usually not very verbose, so you may like to
+ create your own index page.
+ </p>
+ <p>
+ To do this, simply create an <code>index.xml</code> document in the base <code>xdocs</code> directory in the
+ same style as the other documents (as explained in the previous sections), and this will be used instead of
+ the generated document.
+ </p>
+ </subsection>
+ <subsection name="Visual Style">
+ <p>
+ By default, all Maven-generated sites use the same look and feel for consistency.
+ This enables users to easily recognize a Maven-generated site and immediately feel comfortable
+ searching for information on the site.
+ </p>
+ <p>
+ Of course, we understand that users will want to
+ customize their own sites. There are two alternatives.
+ </p>
+ <p>
+ Firstly, you can select different skins. Currently Maven comes with two skins - the current default and the
+ "classic" skin that appeared in Maven 1.0 Beta 10 and earlier. Selection of the skin (and the colours used if
+ using the classic skin) is done through <a href="../reference/plugins/xdoc/properties.html">properties</a>
+ given to the XDoc plugin.
+ </p>
+ <p>
+ The other alternative is to provide your own CSS. The Maven site is generated in XHTML and the layout defined
+ by CSS. The best alternative is to take the existing stylesheet and modify it according to your tastes.
+ To specify the alternate stylesheet, set the <code>maven.xdoc.theme.url</code> property for the XDoc plugin
+ (again, see the <a href="../reference/plugins/xdoc/properties.html">properties</a> for more information).
+ </p>
+ </subsection>
+
+ <subsection name="Reports">
+ <p>
+ Finally, if you want to customize which reports are
+ automatically generated for your site, you need to include the
+ <a href="../reference/project-descriptor.html#reports"><code>reports</code></a> tag
+ in your project descriptor. This tag enables you to
+ selectively choose which reports to include and exclude as
+ well as the order of the reports.
+ </p>
+ <p>
+ The following are the default set of reports, as specified by the XDoc plugin:
+ </p>
+ <source>
+maven-changelog-plugin
+maven-changes-plugin
+maven-checkstyle-plugin
+maven-developer-activity-plugin
+maven-file-activity-plugin
+maven-javadoc-plugin
+maven-jdepend-plugin
+maven-junit-report-plugin
+maven-jxr-plugin
+maven-license-plugin
+maven-linkcheck-plugin
+maven-pmd-plugin
+maven-tasklist-plugin</source>
+ </subsection>
-From the wiki:
-<p>Just slap all the Xdoc information you come across in here. Occasionally I will come back and clean it into a useful repository of how Maven Xdoc works. <p><hr>
- <b>I've discovered the navigation.xml file and can now add links and menu items. How do I add a menu 'header' to navigation.xml in the same style as the generated 'Project Documentation' header (which comes out in HTML within STRONG tags) ?</b> <p>To add a new menu, use the <tt class="wiki"><menu name="Menu Name"></tt> element. Each linkable entry underneath is its own item. <p><hr>
- <b>Is there any way I can specify whereabouts in the navigation.xml Maven adds the 'Project Information' block or is it always at the foot?</b> <p>Not at the moment - <a href="./BenWalding.html">BenWalding</a> <p><hr>
- <b>On the footer that Maven adds with the company name ... is there any way I can make the company name a hyperlink to copyright info for the company?</b> <p>Not at the moment - <a href="./BenWalding.html">BenWalding</a> <p><hr>
- <b>Can I specify to have the Maven footer (2002-2003 company name) just below the line "Last Published ..." ? rather than at the foot of the page ? What is the property entry for this?</b> <p>Not at the moment - <a href="./BenWalding.html">BenWalding</a> <p><hr>
- <b>How can I change the powered by logo?</b> <p>The default powered by logo is "Maven - Propaganda", as decided by the community. For detail about the vote and alternative logos see <a href="http://projects.walding.com/powered/">http://projects.walding.com/powered/</a>. The logo can be changed using the following properties. (See "Maven User Guide" <a href="http://maven.apache.org/reference/user-guide.html#Properties_Processing">http://maven.apache.org/reference/user-guide.html#Properties_Processing</a> for details how to change properties.) <ul><p> <pre class="code">
-# The logo to show on the generated site.
-maven.xdoc.poweredby.image = maven-bolt.png
-maven.xdoc.poweredby.title = Bolted together with Maven
-maven.xdoc.poweredby.url = http://maven.apache.org/
-</pre></ul><p>(While it is possible to change this to anything, that was never it's intention) <p>I think the default has now changed: it appears to be one of the 'button' variants (which is far more professional looking IMHO) <p><hr>
- <b>How can I add images to the navigation?</b> <p>Add an <tt class="wiki">img</tt> attribute to the item element. <ul><p> <pre class="code">
-<item name="The Site" href="http://www.thesite.net/" img="http://www.thesite.net/thesite.png"/>
-</pre></ul><p><hr>
- <b>How do I create collapsible items?</b> <p>Add a <tt class="wiki">collapse="true"</tt> attribute <p>eg. <ul><p> <pre class="code">
-<item name="Design" href="/design.html" collapse="true">
-</pre></ul><p>The <tt class="wiki">href</tt> attribute should be absolute (i.e. href="<b>/</b>design.html"), else the item never gets expanded since the location cannot be resolved by the Navbean. <p><hr>
- <b>How do I add the Google search to my pages?</b> <p>Add a <tt class="wiki"><search/></tt> element to your <tt class="wiki">navigation.xml</tt> file. e.g: <ul><p> <pre class="code">
-<project name="foo">
- <body>
- <menu name="bar">
- ..
- </menu>
-
- <search/>
-</project>
-</pre></ul><p>- from the mailing list (<a class="nonexistent" href="./TimAndersen.html">TimAndersen</a>) <p><hr>
- <b>How do I put HTML in my description?</b> <p>Use html escape notion. e.g: <tt class="wiki">&amp;gt;</tt> <p><hr>
- <b>Can I create my own index page rather than using the autogenerated page from the description?</b> <p>Create an <tt class="wiki">index.xml</tt> file in the <tt class="wiki">xdocs</tt> directory. <p><hr>
- <b>How can I make Maven generate a site without the "Project Documentation" menus?</b>. <p>The default menu can be omitted using the following property: (See "Maven User Guide" <a href="http://maven.apache.org/reference/user-guide.html#Properties_Processing">http://maven.apache.org/reference/user-guide.html#Properties_Processing</a> for details how to change properties.) <ul><p> <pre class="code">
-# Disable Project Documentation: only menu items in navigation.xml items will be generated
-maven.xdoc.includeProjectDocumentation = no
-</pre></ul><hr>
--->
+ <subsection name="Exclusion of All Maven-Generated Content">
+ <p>
+ Users building documentation-only sites or sites that
+ aggregate a lot of sub-projects might want to prevent the
+ inclusion of the entire "Project Documentation" section of the
+ navigation bar on their sites. This can be done by setting
+ the
+ <code>maven.xdoc.includeProjectDocumentation</code>
+ property to the value of
+ <code>no</code>. By default, Maven
+ will include the "Project Documentation" section of the
+ navigation bar which includes information about the project as
+ well as links to the numerous Maven-generated reports.
+ </p>
+ </subsection>
+ </section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org