[Grok-doc] official docs, svn , sphinx, buildout
Aroldo Souza-Leite
asouzaleite at gmx.de
Thu Apr 22 03:19:13 EDT 2010
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,
>
>
More information about the grok-doc
mailing list