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

Phillip J. Eby pje at telecommunity.com
Fri Dec 23 01:41:20 CET 2005

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

More information about the Python-Dev mailing list