PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Fri, 5 Apr 2002 10:03, Andreas Jung wrote:
> [on switching Zope from STNG to ReST]
> Backward compatibilty is a major issue for inclusion into Zope.

This is the major problem facing such a switch, yes. Automatic conversion 
_should_ be possible,  but I have a strong feeling this issue will be a 
blocker. Converting from STNG to ReST is usually just a process of dedenting.


> I still have not figured how to use it.

This is a big issue at the moment - there's a lot of detailed spec and 
related documentation, but nothing solid on the user side of things. I'm 
hoping to help that along with documentation like the primer and a simple 
command-line tool exposing the most commonly needed functionality. At the 
moment, the restructuredtext/tools/html.py script is it (pass it a ReST file 
name and it spits out HTML).


> Are there generators for HTML available yet?

Yep. The primer I just posted uses it. Roundup uses it for its non-docstring 
documentation (only because there's no simple docstring extractor yet). Here 
at ekit we've used it for internal documentation too.

The generation is slow at present. The emphasis has been on implementation, 
and optimisation is yet to come.


    Richard