[Grok-dev] Re: publishing the sphinx driven documentation

[Martijn Faassen]

Hey Kevin,

Kevin Teague wrote:
> Martijn Faassen-2 wrote:
>> * evaluate the current grokdoc work on the trunk
>>
> 
> A few small items:
> 
>  - grok/CHANGES.txt (which is included in the Sphinx docs) is skipping a few
> release notes
>    (0.11.1 and 0.12.1).

This is an artifact of the way we branch releases. I am not sure we 
should do much about this. When we apply fixes to a branch, we have to 
apply them to the trunk too, and update the CHANGES.txt accordingly.

>  - We wanted to have the "About Grok" information only on /about/ on the
>    site, and remove this from the "official release docs", correct?

Yes, I think so.

>  - We have "community documentation" and ... "sphinx driven documentation"
> or
>    "official documentation" or "release documentation"? Any suggestions on
>    how we should refer to these two types of documentation? Right now the 
>    Sphinx docs section has the headline on the home page "Grok
> Documentation".
> 
>    A few of suggestions:
> 
>    * "Grok Core Documentation"
> 
>    * "Official Grok Documentation"
> 
>    * "Essential Grok Documentation"

I think "official documentation" might be the best. I mean, I don't want 
to detract from the community documentation at all as I think it's very 
valuable, but the official documentation does imply extra maintenance 
being done on them.

> Martijn Faassen-2 wrote:
>> * figure out a structure similar to python.org where documentation is 
>> published for each release, with the latest release being the default. 
>> Extend grokdoc to do this if this is necessary.
>>
> 
> We can put these under any URL we want, how about these:
> 
>  http://grok.zope.org/documentation/releases/ <- index of all versions
>  http://grok.zope.org/documentation/releases/current <- latest release
> version
>  http://grok.zope.org/documentation/releases/0.13 <- a specific version

These sound fine.

[snip]
> Martijn Faassen-2 wrote:
>> * the publication should happen in a grok-like layout. Nothing fancy, 
>> just something of a continuation of the theme. I don't know whether 
>> grokdoc does this right now.
>>
> 
> The CSS for the Sphinx docs could use a bit of tweaking. I said I'd do this
> a few months ago - and then promptly did nothing :(. The CSS is "good
> enough"
> right now, but I can fix it up a bit ...
> 
> ... however, each build of the docs (0.13, 0.14, 1.0, etc) will have it's
> own CSS file. If we improve the CSS over time, maybe we want to tweak the
> Sphinx build process to refer to a single common CSS file?
> 
> There is also no way to get from the Sphinx docs back to the web site. There
> is the use-case of having offline docs. Perhaps we should have two Sphinx
> build processes, one for offline and slightly tweaked one that builds them
> for the web site.

I'm trying to understand why the results/these processes need to be 
different?

[snip]
> FYI, I installed CacheFu on the Grok Plone instance last week, but we
> haven't done much configuration with it yet (the idea is to put Varnish in there to
> make the site able to survive traffic spikes).

Cool, I hope we'll get some traffic spikes to survive not too long from 
now. :)

Regards,

Martijn