How to Publish Forrest Documentation

All documentation about Apache Forrest is managed as a Forrest-built project located in the site-author directory of forrest/trunk SVN. The Apapce Forrest website is updated by generating static pages from the site-author-project and committing them to the forrest/site SVN, which is then 'svn checkout' on the forrest.apache.org webserver to create the website.

See other notes for the Documentation Coordinator role.

Do once, create $FORREST_HOME/deploy.svn.settings file. These credentials are needed by forrestbot so that it can do your 'svn add' and 'svn commit' etc. to the forrest/site/ repository. The deploy.svn.settings file looks like:

<?xml version="1.0"?>
<project>
    <property name="deploy.svn.user" value="myApacheUsername"/>
    <property name="deploy.svn.password" value="myPassword"/>
</project>
      

Generating and publishing the main docs is very easy using a local forrestbot:

cd site-author
forrest -f publish.xml build
forrest -f publish.xml deploy

This builds the documentation locally then deploys it by committing it to the forrest/site SVN. Then a cronjob on the server will automatically publish it. However, if instant turnaround is required, then do this:

ssh people.apache.org
cd /www/forrest.apache.org
svn update

Publishing documentation for a particular plugin is done by:

cd plugins/myPluginName
$FORREST_HOME/tools/ant/bin/ant deploy-docs

See further information in the buildPlugin doc.

See some general notes about managing project websites.

There have been a few explantions of our docs processing on the forrest-dev mail list. Need to glean the info from them. Here is the content of some:

                To publish from trunk/site-author/
                
                Do once:
                # Create $FORREST_HOME/deploy.svn.settings file. These credentials
                # are needed by forrestbot so that it can do your 'svn add'
                # and 'svn commit' etc. to the forrest/site/ repository.
                # The deploy.svn.settings file looks like:
                <?xml version="1.0"?>
                <project>
                    <property name="deploy.svn.user" value="myApacheUsername"/>
                    <property name="deploy.svn.password" value="myPassword"/>
                </project>
                
                
                # Make changes to sources, and then test, then commit.
                # Best to wait on committing the source changes until
                # you have built and reviewed the docs.

                # Please, please, ensure valid xml docs. Errors will be
                # reported during the 'build' phase if you don't.
                # Also it prevents other people from working with the docs,
                # which goes against the collaborative development process.

                # You can do 'forrest validate-xdocs" beforehand or use
                # a validating editor (link: catalog.html) or for a single doc use
                # xmllint (link: catalog.html) from the command-line, e.g.
                # xmllint --noout --valid --catalogs faq.xml

                # Use the forrestbot to build and then deploy to svn.apache.org ...
                
                cd site-author
                forrest -f publish.xml build
                # ... verify files in build/forrest-docs
                forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"
                
                Now the files are in SVN at forrest/site
                Periodically the real website files are updated from there.
                You do not have to do anything else.
                
                ----------------------
                Note: The first time that you deploy, it will need to do
                a long svn checkout first.
                
                FIXME: That commit message technique does not work.
                The second word is treated as an ant target to be called.
                Just leave it out and forrestbot will use a default message.
                 
      

Some more notes that need to be integrated above ...

Note that forrestbot does not remove docs from the forrest/site SVN (FOR-392). So need to manually delete: 'cd /svn/forrest/site; svn delete oldDoc'. Then remove it from the forrestbot work directories: 'cd $FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm work/svn-deploy/forrest-docs/oldDoc'.

The generated docs are in build/forrest-docs which is the name given to it in the forrestbot descriptor (site-author/publish.xml). Here is a trick for reviewing changes that forrestbot is ready to deploy ...

forrest -f publish.xml build
svn update work/svn-deploy/forrest-docs
diff -rq build/forrest-docs work/svn-deploy/forrest-docs | grep -v "\.svn" | grep differ