[Grok-dev] tutorial and tutorial samples

[Martijn Faassen]

Hi there,

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 
here:

http://svn.zope.org/grok/trunk/doc/groktut/

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
   :literal:

The 'literal' bit is to make it appear as a a literal code sample in the 
generated HTML.

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

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

Have fun!

Regards,

Martijn