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

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.

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 work/svn-deploy/forrest-docs build/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).