pluto documentation - getting started

[DavidSeanTaylor <da...@bluesunrise.com>]

This email is targeted at those of us on the team who are new to the old documentation process….

I can now get Pluto to generate live documentation. There are a few moving parts that need to be explained. Documentation is sourced in:

1. the Pluto project in Git. We mainly edit the pom.xml here, and then ask Maven to generate documentation and reports for us
    those files get placed in HTML files in target/site after running mvn site

2. A Portals documentation project in Subversion. This project holds all the documentation for Apache Portals. Pluto docs are contained in a subdirectory named pluto.
    You also run mvn site to generate HTML files. These files are output to target/site

3. The “Live” documentation. This subversion repository is ‘live’ meaning once you commit the HTML files then they go live pretty much immediately
  
To get started, of course you must already have checked out portals-pluto! Lets assume that you checked everything under $HOME/apache…

$HOME/apache
	portals-pluto
	site
	pluto-live

# First, checkout the portals site:
cd $HOME/apache
svn co https://svn.apache.org/repos/asf/portals/site

# Then checkout the portals live site, you can save some disk space by only checking out live pluto html :
svn co https://svn.apache.org/repos/asf/portals/site-live/pluto pluto-live

I just made some changes to the documentation, and its now published and live here:

1. Added a message to the news page about Pluto 3.0 upcoming release:
http://portals.apache.org/pluto/news.html <http://portals.apache.org/pluto/news.html>

2. Added Neil to team
http://portals.apache.org/pluto/team-list.html <http://portals.apache.org/pluto/team-list.html>

In the first example, I edited an xml file under the site directory:

cd $HOME/apache/site/pluto
vi src/site/xdoc/news.xml
mvn site
# generates docs in target/site
cp target/site/news.html ../../pluto-live/
svn commit -m “updating news xdocs”
cd ../../pluto-live
 # news.html is ready commit
svn status
svn commit -m “updating live html page immediately”

In the second example, I edited the pom.xml, adding Neil as a part of the team, and then ran

cd $HOME/apache/portals-pluto
# NOTE I run -N for no-recurse. You can run mvn site for the entire project, and it will build, but it creates lots of docs for the TCK test cases and takes a long time to build
mvn site -N
cp target/site/team-list.html $HOME/apache/pluto-live/
cd $HOME/apache/pluto-live
svn commit -m “updating team list”