[Grok-dev] publishing the sphinx driven documentation

Kevin Teague kevin at bud.ca
Thu Jun 12 20:04:52 EDT 2008

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).

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

 - We have "community documentation" and ... "sphinx driven documentation"
   "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

   A few of suggestions:

   * "Grok Core Documentation"

   * "Official Grok Documentation"

   * "Essential Grok Documentation"

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
 http://grok.zope.org/documentation/releases/0.13 <- a specific version

Martijn Faassen-2 wrote:
> * open up an area on grok.zope.org for this to be published.
> * the tutorial and the developer's notes, and a few other .rst files in 
> Grok's "doc" directory in SVN will be published that way. They need to 
> disappear on the Plone part of grok.zope.org.
> * the Plone site should have links into this site, at least to the 
> 'current' version of the documentation, and also a link to the 
> historical documentation.

These items are fairly easy to address. Kamon or I should be able to take
care of this.

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
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 was just playing with an install of this pointed to the grokdocs.

The ability for filesystem content to appear in local site search is quite
nice. Although the search results displayed aren't the most user friendly,
results tend to look like this:

  Search: grok.View
  - tutorial.html
  - functions.html
  - componnents.html

If we index the contents of all released versions (including point releases)
it could pile up pretty fast. You'd get search results like:

  Search: grok.View
  - tutorial.html
  - tutorial.html
  - tutorial.html

Which would be kind of painful I think. It would be best if only the current
release was indexed - if people need to refer to historical docs, then they
can drill down to that content via normal site navigation. Doing all this
make the release process a bit more fiddly though.

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

View this message in context: http://www.nabble.com/publishing-the-sphinx-driven-documentation-tp17798561p17812321.html
Sent from the Grok mailing list archive at Nabble.com.

More information about the Grok-dev mailing list