Author: dennisl
Date: Sat Nov 10 09:33:50 2007
New Revision: 593797
URL: http://svn.apache.org/viewvc?rev=593797&view=rev
Log:
o Add some texts to the site guide that was only available in the getting
started guide.
o Remove practically the whole 'How do I create documentation' section from the
getting started guide. Instead add a link to the site guide, from which this
section seems to have been copied in the first place. We can not have two
copies of the same text.
Modified:
maven/site/trunk/src/site/apt/guides/getting-started/index.apt
maven/site/trunk/src/site/apt/guides/mini/guide-site.apt
Modified: maven/site/trunk/src/site/apt/guides/getting-started/index.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/getting-started/index.apt?rev=593797&r1=593796&r2=593797&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/getting-started/index.apt (original)
+++ maven/site/trunk/src/site/apt/guides/getting-started/index.apt Sat Nov 10
09:33:50 2007
@@ -1115,265 +1115,8 @@
+----+
- If you take a look in your directory structure it should look like the
following:
-
-+----+
-
-my-app-site
-|-- pom.xml
-`-- src
- `-- site
- |-- apt
- | |-- format.apt
- | `-- index.apt
- |-- fml
- | `-- faq.fml
- |-- fr
- | |-- apt
- | | |-- format.apt
- | | `-- index.apt
- | |-- fml
- | | `-- faq.fml
- | `-- xdoc
- | `-- xdoc.xml
- |-- xdoc
- | `-- xdoc.xml
- |-- site.xml
- `-- site_fr.xml
-+----+
-
- The pom.xml should look like this:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
- http://maven.apache.org/xsd/maven-4.0.0.xsd";>
- <modelVersion>4.0.0</modelVersion>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app-site</artifactId>
- <version>1.0-SNAPSHOT</version>
- <name>Maven</name>
- <url>http://maven.apache.org/maven2</url>
- <inceptionYear>2001</inceptionYear>
- <distributionManagement>
- <site>
- <id>website</id>
- <url>scp://webhost.company.com/www/website</url>
- </site>
- </distributionManagement>
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-site-plugin</artifactId>
- <configuration>
- <locales>en,fr</locales>
- </configuration>
- </plugin>
- </plugins>
- </build>
-</project>
-+----+
-
- You will notice there is now a <<<${basedir}/src/site>>> directory within
which is contained a site descriptor
- along with various directories corresponding to the supported document types.
Let's take a look at site
- descriptor and the examples of the various document types.
-
- The Xdoc format is the same as
{{{http://maven.apache.org/maven-1.x/using/site.html} used in Maven 1.0}}.
However, <<<navigation.xml>>>
- has been replaced by the site descriptor (see below).
-
- The APT format, "Almost Plain Text", is a wiki-like format that allows you to
write simple, structured documents (like this one)
- very quickly. A full reference of the {{{../mini/guide-apt-format.html} APT
Format}} is available.
-
- The FML format is the FAQ format, also used in Maven 1.0.
-
- Other formats are available, but at this point these 3 are the best tested.
There are also several possible output formats,
- but as of 2.0, only XHTML is available.
-
- Note that all of the above is optional - just one index file is required in
one of the input trees. Each of the paths will be merged
- together to form the root directory of the site.
-
-* Generating The Site
-
- Generating the site is very simple, and fast!
-
----------------
-mvn site
----------------
-
- The resulting site will be in <<<target/site/...>>>
-
-* {How do I deploy my site?}
-
- To be able to deploy the site, you must first declare a location to
distribute to in your <<<pom.xml>>>, similar to the repository for
- deployment.
-
----------------
-<distributionManagement>
- <site>
- <id>website</id>
- <url>scp://www.mycompany.com/www/docs/project/</url>
- </site>
-</distributionManagement>
----------------
-
- The <<<id>>> element identifies the repository, so that you can attach
credentials to it in your <<<settings.xml>>>
- file in the same way as you would for any other repository. The URL gives
the location to deploy to. Currently,
- only SSH is supported, as above which copies to the host
<<<www.mycompany.com>>> in the path <<</www/docs/project/>>>.
-
- Deploying the site is done with the <<<site-deploy>>> goal. Note that you
cannot just call the deployment goal on its own, however.
- You must presently run the <<<site>>> goal independently.
-
----------------
-mvn site-deploy
----------------
-
- <<Note:>> the trailing slash in the URL above indicates that any subprojects
that inherit this value should append their artifact ID to
- the path instead of using it as is.
-
-* Creating a Site Descriptor
-
- The <<<site.xml>>> file is used to describe the layout of the site, and
replaces the navigation file used in Maven 1.0.
-
- A sample is given below:
-
---------------------
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<project name="Maven">
- <bannerLeft>
- <name>Maven</name>
- <src>http://maven.apache.org/images/apache-maven-project.png</src>
- <href>http://maven.apache.org/</href>
- </bannerLeft>
- <bannerRight>
- <src>http://maven.apache.org/images/maven-small.gif</src>
- </bannerRight>
- <body>
- <links>
- <item name="Apache" href="http://www.apache.org/"; />
- <item name="Maven 1.0" href="http://maven.apache.org/maven-1.x"/>
- <item name="Maven 2" href="http://maven.apache.org/"/>
- </links>
-
- <menu name="Maven 2.0">
- <item name="Introduction" href="index.html"/>
- <item name="Download" href="download.html"/>
- <item name="Release Notes" href="release-notes.html" />
- <item name="General Information" href="about.html"/>
- <item name="For Maven 1.0 Users" href="maven1.html"/>
- <item name="Road Map" href="roadmap.html" />
- </menu>
-
- <menu ref="reports"/>
-
- ...
- </body>
-</project>
---------------------
-
- ~~TODO: deserves more explanation.
-
- Note the <<<\<menu ref="reports"/\>>>> string in the navigation. When
building the site, this is replaced by menus for any reports
- that you have configured.
-
-* Adding Extra Resources
-
- You can add any arbitrary resources to you site by including them in a
- <<<resources>>> directory as shown below. Additional CSS files will be
picked up
- when they are placed in the <<<css>>> directory within the <<<resources>>>
- directory.
-
--------------------
-+- src/
- +- site/
- +- resources/
- +- css/
- | +- site.css
- |
- +- images/
- +- pic1.jpg
---------------------
-
- The file <<<site.css>>> will be added to the default XHTML output, so it can
be used to adjust the default Maven stylesheets if desired.
-
- The file <<<pic1.jpg>>> will be available via a relative reference to the
<<<images>>> directory from any page in your site.
-
-* Configuring Reports
-
- Maven has several reports that you can add to your web site to display the
current state of the project.
- These reports take the form of plugins, just like those used to build the
project.
-
- To add these reports to your site, you must add the plugins to a special
<<<reporting>>> section in the POM. The
- following example shows how to configure the standard project information
reports that display information from the
- POM in a friendly format:
-
--------------------
-<project xmlns="http://maven.apache.org/POM/4.0.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
- http://maven.apache.org/xsd/maven-4.0.0.xsd";>
- ...
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-project-info-reports-plugin</artifactId>
- </plugin>
- </plugins>
- </reporting>
- ...
--------------------
-
- If you have included the appropriate <<<${reports}>>> tag in your
<<<site.xml>>> descriptor, then when you regenerate
- the site those items will appear on the menu.
-
- ~~TODO: explain report sets
-
-* Internationalisation
-
- Internationalisation in Maven is very simple, as long as the reports you are
using have that particular locale
- defined.
-
- To enable multiple locales, add configuration similar to the following to
your POM:
-
--------------------
-<project xmlns="http://maven.apache.org/POM/4.0.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
- http://maven.apache.org/xsd/maven-4.0.0.xsd";>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
- <configuration>
- <locales>en,fr</locales>
- </configuration>
- </plugin>
- </plugins>
- ...
--------------------
-
- This will generate both an English and a French version of the site. If
<<<en>>> is your current locale, then it will
- be generated at the root of the site, with a copy of the French translation
of the site in the <<<fr/>>> subdirectory.
-
- To add your own content for that translation instead of using the default,
place a subdirectory with that locale
- name in your site directory and create a new site descriptor with the locale
in the file name. For example:
-
--------------------
-+- src/
- +- site/
- +- apt/
- | +- index.apt (Default version)
- +- fr/
- | +- apt/
- | | +- index.apt (French version)
- +- site.xml (Default site descriptor)
- +- site_fr.xml (French site descriptor)
---------------------
-
- With one site descriptor by language, a translated site can evolve
independently.
+ Now head on over to the {{{../mini/guide-site.html}Guide to creating a site}}
+ to learn how to create the documentation for your project.
* {How do I build other types of projects?}
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-site.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-site.apt?rev=593797&r1=593796&r2=593797&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-site.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-site.apt Sat Nov 10
09:33:50 2007
@@ -30,10 +30,14 @@
+- site.xml
--------------------
+ You will notice there is now a <<<$\{basedir\}/src/site>>> directory within
which is contained a site descriptor
+ along with various directories corresponding to the supported document types.
Let's take a look at site
+ descriptor and the examples of the various document types.
+
The Xdoc format is the same as
{{{http://maven.apache.org/maven-1.x/using/site.html} used in Maven 1.x}}.
However, <<<navigation.xml>>>
has been replaced by the site descriptor (see below).
- The APT format, "Almost Plain Text", is a wiki-like format that allows you
to write simple, structured documents (like this)
+ The APT format, "Almost Plain Text", is a wiki-like format that allows you
to write simple, structured documents (like this one)
very quickly. A full reference of the {{{guide-apt-format.html} APT Format}}
is available.
The FML format is the FAQ format, also used in Maven 1.x.
@@ -78,12 +82,15 @@
file in the same way as you would for any other repository. The URL gives
the location to deploy to. Currently,
only SSH is supported, as above which copies to the host
<<<www.mycompany.com>>> in the path <<</www/docs/project/>>>.
+ <<Note:>> the trailing slash in the <<<\<url\>>>> above indicates that any
subprojects that inherit this value should append their <<<artifactId>>> to
+ the path instead of using it as-is.
+
+ Deploying the site is done by using the <<<site-deploy>>> phase of the site
+ lifecycle.
+
---------------
mvn site-deploy
---------------
-
- <<Note:>> the trailing slash in the URL above indicates that any subprojects
that inherit this value should append their <<<artifactId>>> to
- the path instead of using it as-is.
* Creating a Site Descriptor
