[Grok-doc] official docs, svn , sphinx, buildout

[Uli Fouquet]

Hi Aroldo,

Aroldo Souza-Leite wrote:

> I would like to check out the official rst-Grok documentation and build 
> it locally. My aim is to document my own Grok projects for internal 
> usage as an extension of the official Grok documentation.
> 
> Please give me a hint on:
> 
> - how to check it out  from (http://svn.zope.org/grok/trunk/doc/), 
> because this svn address seems to be the wrong one (sorry, I already 
> asked this question but lost track of the thread).

While the doc/ subdir contains the sphinx sources to feed sphinx (i.e.
all the texts to be rendered, layout, etc.), the grokdocs/ subdir
contains an extra-egg which defines the two commands `grokdocs2html` and
`grokdocs2latex`. Basically, these commands start sphinx with
appropriate environments set, mainly .

The grokdocs package expects to find the ReST sources in a directory
named 'doc', located on the same directory level as the grokdocs/ tree
(so you need both directories). This is ugly, I know.

To finally build the documentation using zc.buildout you can define a
buildout rule like this in your project (copied from groks
buildout.cfg)::

  [buildout]
  ...
  parts = 
    ...
    docs
    ...
  develop =
    .
    grokdocs
    # any other local eggs...

  ...

  [docs]
  recipe = zc.recipe.egg
  eggs = grokdocs

  ...

Running buildout then should generate the commands.

> - how to use the same buildout sphinx project used by the official 
> documenters in order to have
> 
> $ bin/grokdocs2html
> and
> $ bin/grokdocs2latex
> 
> like it is explained in 
> 
> (http://grok.zope.org/doc/current/README.html)

I hope the above remarks can help in that respect. I would, however,
*not* recommend to do this in own projects. The reason why this
doc-building procedure is so over-complicated is simple: when writing
this piece (the grokdocs/ package), sphinx was very new and in the very
beginning even didn't exist on PyPI. The grokdocs package added some
extras like Pygments support, that where not available with sphinx at
time of writing grokdocs.

Meanwhile there is a bunch of zc.buildout recipes available that can
generate the whole docs in a much plainer manner.

Also most of the 'fixes' applied by `grokdocs` commands, meanwhile made
it into the sphinx standard distribution (not to mention all the cool
other features like autotests and the like), so instead copying the
grokdocs approach, I'd rather opt for updating grok itself and go the
'standard approach' of other Python projects using more recent sphinx
versions and buildout recipes.

I see that someone actually has to do it, so if you like, we could do
that together :-)

Best regards,

-- 
Uli

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-doc/attachments/20100421/c8462cb7/attachment.bin