[Grok-dev] Re: is automatic context detection harmful?

[Brandon Craig Rhodes]

Martijn Faassen <faassen at startifact.com> writes:

> I don't think the grok.context() rule is so hard to understand.
> Almost all the grok directives have a default. If you leave it out,
> the default behavior will kick in.

Ah!  I begin to understand!  If we followed to its logical conclusion
my argument that requiring grok.context() makes code more legible, we
would have to always require *every* Grok directive, which would mean
dozens of Grok statements everywhere from now on.  But, instead, both
the grok.context() directive and every other Grok directive is going
to always have the Most Useful Default possible, so that in as many
places as possible they disappear.

If I understand that correctly - and thanks for your long and helpful
reply - then there is a new piece of documentation I would like.

I want a concise document showing, for every class that can be
decorated with Grok directives, the list of every single Grok
directive that applies to that class, and gives the default value.
Because, I now see, when I write a simple Model or View, even if I
include grok.context() to make things more explicit, there are
probably several other directives I don't even know about for which
Grok is silently choosing reasonable defaults that I therefore never
have to think about.  It would be neat to have one place of reference
to see what they are and what they default to.

I would be happy to start such a document if none exists (is it
somewhere I haven't looked yet?).

Such a document would not be like a "tutorial", and only a little like
a "recipe".  It could even go by the separate name of "Reference",
maybe called "the Grok Reference", because it seems to me that it
would have the same place in our documentation as the Python Reference
has for Python - the place you go for the dry, technical, final
explanation of everything that Grok allows.

I would also love the Grok Reference to have a short, brief, and
exhaustively correct description of how Grok/martian iterates across
my application - all in one place, the rules about what directories it
enters, which it ignores, and exactly how it finds my modules and
templates.  Which might be helpful when beginners are debugging "Why
doesn't Grok see my class"!

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon