[Grok-dev] New Grok site: restructured text and HTML

[Kevin Teague]

>
>
>  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  
> or
> 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  
ReST ...


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

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

http://plone.org/documentation/manual/plone-3-user-manual