[Python-Dev] Pydoc Improvements / Rewrite

[Talin]

Ron Adam wrote:
> Larry Hastings wrote:
>> For those of us without eidetic memories, PEP 287 is "use 
>> reStructuredText for docstrings":
>>     http://www.python.org/dev/peps/pep-0287/
> 
> Thanks for the link. PEP 287 looks to be fairly general in that it expresses a 
> general desire rather than a specification.

Apologies for the digression, but I have a comment on this.

Rather than fixing on a standard markup, I would like to see support for 
a __markup__ module variable which specifies the specific markup 
language that is used in that module. Doc processors could inspect that 
variable and then load the appropriate markup translator.

Why? Because its hard to get everyone to agree on which markup language 
is best for documentation. I personally think that reStructuredText is 
not a good choice, because I want to add markup that adds semantic 
information, whereas reStructuredText deals solely with presentation and 
visual appearance. (In other words, I'd like to be able to define 
machine-readable metadata that identifies parameters, return values, and 
exceptions -- not just hyperlinks and text styles.) Having used a lot of 
different documentation markup languages, and written a few of them, I 
prefer "non-invasive" semantic markup as seen in markup processors such 
as Doc-o-matic and NaturalDocs. (By non-invasive, I mean that the markup 
doesn't detract in any way from the readability of the marked-up text. 
Doc-o-matic's markup language is very powerful, and yet unless you know 
what you are looking for you'd think its just regular prose.) I have a 
prototype (called "DocLobster") which does similar types of processing 
on Python docstrings, but I haven't publicized it because I didn't feel 
like competing against ReST.

However, I realize that I'm in the minority with this opinion; I don't 
want to force anyone to conform to my idea of markup, but at the same 
time I'd prefer not to have other people dictate my choice either.

Instead, what I'd like to see is a way for multiple markup languages to 
coexist and compete with each other on a level playing field, instead of 
one being chosen as the winner.

-- Talin