[Grok-dev] tutorial and tutorial samples
faassen at startifact.com
Fri Mar 16 17:40:15 EDT 2007
I've done some work to make sure that each tutorial section has an
actual sample association associated with it with all the code in it.
I've had a bit of buildout help from Jim Fulton to make this sample
application very easy and quick to install. The sample applications are
See the INSTALL.txt for information on how to set them up quickly.
The tutorial.txt file now actually includes its sample code in the
sample applications, using include statements like this:
.. include:: groktut/some_sample/src/sample/app.py
The 'literal' bit is to make it appear as a a literal code sample in the
Doing this allows us to maintain the testable applications in one place
without duplication their code in the tutorial.
This means that if you change grok in a way that requires changes to the
tutorial, you need to update not only the tutorial text but also the
code samples (and test them).
** Want to contribute to Grok? Here's an easy way! **
Not everything has been transformed to use this pattern yet. I stopped
at the 'Completely python-driven views' section. If you follow my
checkin comments and read the code, you approximately know how to
continue and finish it up (making me very happy! :):
$ cd groktut
$ svn copy existing_section_close_to_it new_section
.. edit new_section/src/sample/app.py and so on with code from the
$ cd new_section
$ ../buildout -N
$ parts/instance/bin/zopectl fg
Test whether the sample actually works as described in the tutorial
using a web browser.
Then edit doc/tutorial.txt and include code in it. Test whether your
editing is correct using:
$ rst2html tutorial.txt > tutorial.html
And then open the resulting html in a browser to see whether the literal
sections look okay.
If everything's okay, svn commit the tutorial.txt, svn add anything
necessary in new_section, and svn commit new_section too.
More information about the Grok-dev