[Grok-dev] Re: zc.buildout tutorial

[Uli Fouquet]

Hi Martijn,

On Fri, 03.08.2007, 14:50 +0200 Martijn Faassen wrote:

> [snip: Darryl is busy]

> Understood that you're busy. The trouble with the zc.buildout tutorial 
> is that we won't be maintaining it in the doc/ directory - it's 
> somewhere else in SVN. I don't know what needs tweaking on grok.zope.org 
> to make it appear.

Ooh, things might get complicated here:

I already built a rendered version of the tutorial which I could check
into the doc/ and/or the www/ directory (plus links in the appropriate
index.txt) almost immediately. I googled around a bit, but could not
find a rendered version of the document, at least none, which would be
permanently linkable from the grok homepage.

So, from my point of view, it would make sense to keep a rendered
version of the tutorial in the grok docs, although it had to be
maintained.

Another problem while rendering the tutorial: Jim makes use of the
'code-block:: Python' directive, which is currently not a official part
of docutils and cares for highlighting Python source code fragments.
grok2html uses the stock docutils only and therefore fails with the
original version. 

We could, however, introduce support for syntax highlighting into
grok2html (which would require additional packages to be installed and a
decision, which highlighting engine to use), or just render the source
code in the tutorial as ordinary raw text. I, personally, would prefer
to wait for docutils to introduce built-in highlighting support in the
'official' package. 

In summary, we could

 - link in the external rest file, but it could not be rendered 
   automatically by grok2html (don't know, how to 'link in' a single 
   external source file).

 - link in the external rest file and change grok2html.py to support
   syntax highlighting (additional packages required).

 - maintain a modified version of the tutorial, which works 
   out-of-the-box, but needs maintenance.

 - drop the tutorial text and link to the subversion sources.

> Another feature that would be good for the howto section is author credits.

What about CREDITS.txt in the root?

Cheers,

-- 
Uli