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

[Aroldo Souza-Leite]

Hi Uli,

thanks a lot for the answer. I want to start working on your remarks. 
But before I start reading them more carefully, I have a small silly 
problem:

$ svn co http://svn.zope.org/grok/trunk/doc/ doc

throws the error

svn: Das Projektarchiv wurde permanent nach »/grok/trunk/doc/« 
verschoben; bitte umplatzieren

which means that the project has been moved to the very place where I'm  
trying to check it out from.

I asked this in this list already, but I lost the thread with the 
answer. Sorry for the repetitiveness.

Regards,

Aroldo

Uli Fouquet wrote:
> 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,
>
>