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