[Python-Dev] reST limitations? (was Re: status of development documentation)

[Phillip J. Eby]

At 04:08 PM 12/22/2005 -0500, Martin Blais wrote:
>ReST does an amazing job of inferring generic document structures from
>text, but for documenting source code, you really want to be able to
>say "This is a function", "this is an optional argument", etc.  ReST
>does not provide this kind of functionality, and if you try to stretch
>the interpreted roles to do this you get an equally ugly syntax as
>LaTeX input (I would even argue that I prefer the LaTeX source).

That sounds like a misuse of the tool to me; if you need structured, 
extractable information from a reST document, fields and directives are 
probably going to be the way to go.  Similarly, I'd suggest that 
interpreted roles to identify the context of a name probably isn't the best 
way to go about it either; a link to the definition of the referenced item 
will be more useful and more uniform.  A formatter or intermediate 
processor can then decide whether it should actually be rendered as a 
hyperlink, a fully-qualified name, or just the function/method/class name.

So, definitions of functions, classes, and other structured stuff would 
just use fields under a directive, and references to those definitions 
would just be reST links.


>Also, ReST has many gotchas: if you will infer structures from
>invisible markup, it's very easy to make mistakes, and there are many
>cases where it's not clear what the parsed document will be like, you
>have to "learn" a lot of how it parses the documents, and the corner
>cases, by checking with rst2pseudoxml.py.

Huh?  I've never used rst2pseudoxml.py, so I don't understand how it's a 
requirement.  Do you mean, if you're writing some kind of reST processor 
it's helpful to understand how stuff is parsed?

Can you list some of these "gotchas"?  I've on maybe two occasions had to 
add a backslash to something to prevent it being interpreted as markup, and 
that's about it, although I've written many hundreds of K of Python 
documentation in reST.  (Not the Python core documentation, but other open 
source projects written in Python.)