[Grok-dev] New Grok site: restructured text and HTML
uli at gnufix.de
Wed Jan 16 10:39:26 EST 2008
I am happy to see, that the number of howtos, tutorials and the like on
the new grok site is growing really fast since we switched to the Plone
site. Many thanks to all contributers!
Most of the new documents were written in HTML (with Kupu, I assume).
IMHO this is problematic, because we can not easily convert it to
Restructured Text which in turn makes it difficult to include your
documents in any new grok release documentation.
Kevin already told here on the list, how you can enable
restructuredText-mode for editing, which I will repeat here for
1) Go to:
and disable Kupu.
2) Add/edit your document and enable 'restructured text' as mode for
content editing (this does not seem to work for descriptions).
Note, that you might have to reset this each time before saving
If you're in a hurry, you might still use Kupu/HTML, because HTML is
better than nothing, but consider to convert your documents later on or
drop me a note, so I can do it for you.
Restructured Text is really easy to learn. You can get a first
For writing reference-API documentation, you might want to use the
extended set of ReST markup that is supported by the new Grok-Site. This
extended markup is explained roughly here::
A usage example is the reference itself.
There is also the possibility to stop maintenance of `doc/` in the grok
trunk or to reduce it to a minimum number of README files pointing to
the website. Then it wouldn't matter, in which format documents are
created. The drawback would be, that there would be no 'canonical'
documentation of certain versions. Switching to HTML also in the trunk
documentation is not an option IMHO.
Meanwhile, I added the complete reference documentation from the trunk
to the new site (ReST-format, of course, but still unpublished; only
logged in users can see it). Kevin and me managed to get all special
markup of the reference to be parsed without warnings/errors (thanks,
Kevin!), although the rendered output is still under (CSS-)construction.
People who checked out the gzo-packages to build a local grok-site,
might want to update their sources.
BTW: PloneHelpCenter documents are great in processing standalone ReST
docs. But problems arise, when you link to other internal
documents. TocTrees, for example, are not generated, because
they would have to process several 'files'/documents. Is there a
Plone product, that can handle complete 'trees' of rest documents?
Or should one be written? Could PHC be extended to support such
processing? To summarize: an import/export action would be nice
here. Maybe I am to dumb to see an already available way.
More information about the Grok-dev