[Grok-dev] New Grok site: restructured text and HTML
kevin at bud.ca
Fri Jan 18 03:33:06 EST 2008
> 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
> your document.
Descriptions must be plain, unformatted text as wiggy pointed out.
They get used in RSS feeds and other contexts where ReST and HTML
don't make sense. I filed a bug in PHC about this, and am planning on
submitting a fix for this as well.
> 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
> drop me a note, so I can do it for you.
Kupu is better than anything :). I wrote some docs in ReST, but then I
reverted to HTML because it's what I'm comfortable with. I'm getting
more comfortable with ReST though - I wrote the "our preferred format
is ReST" doc in ReST :). It would be very cool if Kupu generated
> There is also the possibility to stop maintenance of `doc/` in the
> 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.
We should definitley clean-up the doc/ directory in Grok. There are
things like the old static web site publishing tool, which we ship in
the Grok tarball which it makes no sense to do.
The Tutorial and the Reference API are the big ones to have in the /
doc/ directory right now. Figuring out which docs to pull from the web
site and how is a bit of a project. There are currently 1600+ pages in
the plone.org documentation area, it makes sense that we will over
time address the "long tail" of Grok documentation on the web site and
have docs that are of only marginal interest to many Grokkers. We
could perhaps have a keyword, or just pull the highlighted content out
the site for inclusion into /doc/.
> 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.
I was trying to figure out how to automate the importing of the
current Grok Tutorial/Book into the web site - I've come to the
conclusion that it's non-trivial ... for the Tutorial I've punted at
the moment and just put this up as one giant page like we had it on
the old site (http://plone.grok.quintagroup.com/documentation/book).
Longer term as this becomes the Grok book, we should probably split it
out into a Chapter-per-file format in SVN. This would make it a lot
easier to automatically import into the web site, as well as being
more user friendly on the filesystem.
The "Reference Manual" content type generates ToC Trees based on the
internal structure of the content objects, e.g.:
More information about the Grok-dev