[Grok-dev] Re: updating the tutorial
Philipp von Weitershausen
philipp at weitershausen.de
Mon Mar 19 21:03:13 EDT 2007
Martijn Faassen wrote:
> class Index(grok.View):
> pass # see app_templates/index.pt
Ooops, not documenting that was an oversight.
> There's also an ``app_templates`` directory that we ignore in the first
> tutorial section now.
> That's not a good start for anyone following the tutorial: the code they
> see when following the instructions isn't the same as what the tutorial
> says it should be.
> So, the lesson for everybody is that when you update the tutorial,
> *also* update doc/groktut. I'll update it for you this one time. :)
> P.S. I realize updating the tutorial is another step and rather a pain.
I'll add that it is a *major* pain right now, the way it is set up with
lots of independent buildouts that have to be run each time (which takes
ages and doesn't exactly create a flat directory structure for us).
Another painful thing was that a separate grok eggs gets downloaded
instead of the development egg in src/grok being used. I tried to fix
that but the only way that really worked for me was to change each
section's buildout.cfg like so::
-develop = .
+develop = . ../../..
extends = ../buildout_tut.cfg
Of course, I didn't change every file since I wonder if there's be a
better way. What do the buildout masters say?
> It's essential to the success of this project however. I've tried to
> make setting up the examples as fast as possible too: read
Thank you for taking the time to write this down. I'm inclined to argue
that we shouldn't make people update the tutorial on a mandatory basis.
People will be sloppy (just look at me :)) and people will not always
get it right. Also, I plan to do some work on the reference soon. If we
made people update that at the same time, we'll increase the burden even
further (not to mention we already make people write doctests, which is
a good thing but it's a burden).
I realize the importance of the documentation, but I'd hate to see the
bar for Grok development raised too much.
http://worldcookery.com -- Professional Zope documentation and training
More information about the Grok-dev