Apache Software Foundation > Apache Forrest
 
Font size:      

How to Publish Forrest Documentation

This documents the steps to update the Forrest Website.

Introduction

All documentation about Apache Forrest is managed as a Forrest-built project located in the site-author directory of forrest/trunk SVN. The Apache 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 Coordination tasks.

Updating the site with a local forrestbot

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

Note: if your system username is not the same as your "svn username" then provide a "deploy.svn.settings" file as explained at $FORREST_HOME/etc/publishing_our_site.txt

This builds the documentation locally then deploys it by committing it to the forrest/site SVN. The svnpubsub system automatically kicks in to do the final publish step.

See more detailed explanation of this procedure.

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.

Fixme (open)
This is work in progress.

Other docs

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/
                
                # Make changes to sources, and then test, then commit.

                # 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.
                 
      

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: 'svn delete https://svn.apache.org/repos/asf/forrest/site/.../oldDoc' and 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

If you change something that affects all pages (e.g. layout changes; navigation menu additions or MOTD changes that affect old "versioned docs") then see the note in conf/cli.xconf about temporarily not excluding old "docs_*" patterns.

If there have been changes to tools/forrestbar then need to follow the instructions there to build it. Then copy its build/forrestbar.xpi to site-author/content/xdocs/tools/forrestbar.xpi and commit that. Then run forrestbot to build and deploy the site, or alternatively for a quick fix, just commit it to forest/site/tools (which is what forrestbot would do).