Updating the Official Grok Documentation (OGD)
The core Grok documentation is managed inside the Grok project in the doc sub-directory in ReStructured Text format, and Sphinx is used to generate the HTML version of this documentation.
Improving the Documentation
Improving the Grok docs is very simple.
See a mistake or section is missing details in the documentation? Checkout the Grok project from SVN, then run buildout. This will install ./bin/grokdocs2html. Running this program will invoke the Sphinx build, which will convert all of the ReST files in the grok/doc/ directory into HTML. The output will be placed in ./build/html/. Make changes to the docs, re-run grokdocs2html, and see the results of your changes. When happy, commit your changes to SVN.
Publishing the Documentation
For each release of Grok, a snapshot of the docs should be built from the release.
There is a cron-job run daily on the server that updates the /doc/dev/ with the latest version in trunk.
The shell script run by this cron-job can also be used to build the docs from a tagged release. The script 'build.sh' is at:
/var/www/build-html
This is a checkout of http://svn.zope.org/grok/website/build-html/
Modify http://svn.zope.org/grok/website/build-html/build.sh and add a line at the bottom (there are instructions in the script) to tell it about a new release. Update /var/www/build-html again.
The structure of the docs on the server should be:
/var/www/html/grok/doc/ # root doc home, URL is http://grok.zope.org/doc/ /var/www/html/grok/doc/dev # build of the docs from the latest Grok trunk /var/www/html/grok/doc/current # Symlink pointing to the newest stable release /var/www/html/grok/doc/0.13 # build of the docs corresponding to a released version
