[Python-Dev] The docs, reloaded

[Ron Adam]

Nick Craig-Wood wrote:
> Georg Brandl <g.brandl at gmx.net> wrote:
>>  Nick Craig-Wood schrieb:
>>> Being a seasoned unix user, I tend to reach for pydoc as my first stab
>>> at finding some documentation rather than (after excavating the mouse
>>> from under a pile of paper) use a web browser.
>>>
>>> If you've ever used pydoc you'll know it reads docstrings and for some
>>> modules they are great and for others they are sorely lacking.
>>>
>>> If pydoc could show all this documentation as well I'd be very happy!
>>>
>>> Maybe your quick dispatch feature could be added to pydoc too?
>>  It is my intention to work together with Ron Adam to make the pydoc <->
>>  documentation integration as seamless as possible.
> 
> So I'll be able to read the main docs for a module in a terminal
> without reaching for the web browser (or info)?  That would be great!
> 
> How would pydoc decide which bit of docs it is going to show?

Pydoc currently gets topic info for some items by scraping the text from 
document 'local' web pages.  This is kind of messy for a couple of reasons.
    - The documents may not be installed locally.
    - It can be problematic locating the docs even if they are installed.
    - They are not formatted well after they are retrieved.

I think this is an area for improvement.

This feature is also limited to a small list where the word being searched 
for is a keyword, or a very common topic reference, *and* they are not 
likely to clash with other module, class, or function names.

The introspection help parts of pydoc are completely separate from topic 
help parts.  So replacing this part can be done without much trouble.  What 
the best behavior is and how it should work would need to be discussed.

Keep in mind doc strings are meant to be more of a quick reference to an 
item, and Pydoc is the interface for that.


> If I type "pydoc re" is it going to give me the rather sparse __doc__
> from the re module or the nice reST docs?  Or maybe both, one after
> the other?  Or will I have to use a flag to dis-ambiguate?

If retrieval from the full docs is desired, then it will probably need to 
be disambiguated in some way or be a separate interface.

    help('re')        # Quick reference on 're'.
    helpdocs('re')    # Full documentation for 're'.


> If you type "pydoc re" at the moment then it says in it
> 
>   MODULE DOCS
>       http://www.python.org/doc/current/lib/module-re.html
> 
> which is pretty much useless to me when ssh-ed in to a linux box half
> way around the world...
> 
>>> It is missing conversion of ``comment'' at the moment as I'm sure you
>>> know...
>>  Sorry, what did you mean?
> 
> ``comment'' produces smart quotes in latex if I remember correctly.
> You probably want to convert it somehow because it looks a bit odd on
> the web page as it stands.  I'm not sure what the reST replacement
> might be, but converting it just to "comment" would probably be OK.
> Likewise with `comment' to 'comment'.
> 
> For an example see the first paragraph here:
> 
>   http://pydoc.gbrandl.de/reference/index.html
>