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">&lt;menu&#160;name="Menu&#160;Name"&gt;</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">
-&lt;item name="The Site" href="http://www.thesite.net/" img="http://www.thesite.net/thesite.png"/&gt;
-</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">
-&lt;item name="Design" href="/design.html" collapse="true"&gt;
-</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">&lt;search/&gt;</tt> element to your <tt class="wiki">navigation.xml</tt> file. e.g: <ul><p> <pre class="code">
-&lt;project name="foo"&gt;
-  &lt;body&gt;
-    &lt;menu name="bar"&gt;
-       ..  
-    &lt;/menu&gt;
-
-    &lt;search/&gt;
-&lt;/project&gt;
-</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;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