How to Publish Forrest Documentation
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
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 quicker turnaround is required, then do this:
ssh people.apache.org cd /www/forrest.apache.org svn update
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.
original 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/ 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
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).