[Python-Dev] The docs, reloaded

[Nick Craig-Wood]

On Wed, May 23, 2007 at 12:46:50PM -0500, Ron Adam wrote:
> Nick Craig-Wood wrote:
> >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.

And it would be improved by converting the docs to reST I imagine.

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

I think that if reST was an acceptable form for the documentation, and
it could be auto included in the main docs from docstrings then you
would find more modules completely documented in __doc__.

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

Actually if it gave both sets of docs quick, then long, one after the
other that would suit me fine.

-- 
Nick Craig-Wood <nick at craig-wood.com> -- http://www.craig-wood.com/nick