[Grok-dev] [website] Improving ReST support

[Uli Fouquet]

Hi Kevin, 

Kevin Teague wrote:

> Uli Fouquet wrote:
> > 
> > I put the reference core page into
> > the CMS but currently many directives and roles are not handled and
> > generate warnings and error messages. Is there a chance to get support
> > for this (standard python documentation) tags? Can we help out in some
> > way? Or should the reference go back to the standard docutils set of
> > tags?
> 
> I was digging through docutils docs yesterday, but it was late at night and
> I was very tired and I couldn't find a good place where these standard
> Python directives are documented or example code that uses them.
> 
> If anyone can point me to right places that would be appreciated. I don't
> think adding these directives is too difficult.

Nice to hear that! All these information is also hard to find at
daytime ;-) It's relatively new but 

	http://docs.python.org/dev/documenting/

might help you for the beginning. I am currently writing docutils
parsers, writers etc., that provide the additional roles and directives,
but I have to confess, that it was easier to extract these information
from source, especially the ``sphinx`` package. ``sphinx`` is part of
the python doctools::

	http://svn.python.org/projects/doctools/trunk/

To start, I'll put all self-written materials, including roles and
directive documentation into a sandbox branch::
	http://svn.zope.org/Sandbox/ulif/grok-reference-with-rest2/doc/grokref/

(this is currently really sandbox stuff; do not expect something therein
to work correctly ;-)

>  Longer term it would also be
> nice to have additional CSS style for elements marked as a "Python Function"
> or "Python Module", etc. 

The modified docutils parsers should provide special ids for the new
entities to enable special markup of functions, modules, <whatever...>.

> We are also using Pygments which can do Python
> syntax highlighting but I've not yet tried to figure out why/how the Python
> code on the site is not syntax highlighted.

I have no idea how to intergrate all that with Plone, because I am a
complete idiot in that respect. Please tell, if I can help anyhow.

> I'll keep plunking on these issues, but if anyone wants to help out that
> would also be much appreciated :)

Thank you very much! I'll do, what I can. Just tell me, what you need.

Kind regards,

-- 
Uli