[Python-Dev] reST limitations? (was Re: status of development documentation)
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