Personal tools
You are here: Home Project Meta Updating the Official Grok Documentation (OGD)

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