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”
