[Python-Dev] Pydoc Improvements / Rewrite

[Ron Adam]

Talin wrote:
> 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.

How about if plain text be the default, with the ability to over ride it to 
generate another type of output?  This is pretty much the design I'm following. 
  It doesn't choose any markup style or have a preference other than plain text.

Basically you import the gettext module, then add methods to the class's for 
each section to produce the marked up output you want. Then add a few functions 
to assemble it into a page.  I'm sure there's room for improvements, but this 
seems like the most direct way to do it.

Pydoc doesn't just process doc strings.  If that was all there was to it, then 
it would be much easier to automate in a generalized way.  Each section, may get 
it's data from different sources other than doc strings, and those may need to 
be handled in special ways, especially in the cases where it is nested within 
other sections.  This is what makes it difficult to generalize into a sequential 
producer to consumer pattern.  Not weather or not the doc string has additional 
markup in it.

I think the main goal for 2.6 should be a cleaned up package with some modest 
user interface and API improvements.  But also to keep things open ended for 
later enhancements.


[Maybe for python 3.0]

While reading some of the other discussions on multi-methods, generic functions, 
  and ABC's with mixins, it occurred to me that pydoc may be a good place to 
test some of those ideas in.  It's complex enough of a problem that it may 
benefit from those more advanced python features.

But I think that we shouldn't wait for those to do a basic face lift now.  Think 
of it a preliminary clean up if you will in this case.

Ron