[Python-Dev] The docs, reloaded

[Ron Adam]

Nick Craig-Wood wrote:
 > 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.

Yes, this will need a reST to html converter for displaying in the html 
browser.  DocUtils provides that, but it's not part of the library. (?)

And for console text output, is the unmodified reST suitable, or would it 
be desired to modify it in some way?

Should a subset of the main documents be included with pydoc to avoid the 
documents not available messages if they are not installed?

Or should the topics retrieval code be moved from pydoc to the main 
document tools so it's installed with the documents.  Then that can be 
maintianed with the documents instead of being maintained with pydoc.  Then 
pydoc will just looks for it, instead of looking for the html pages.


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

That would be fine for third party modules if they want to do that or if 
there is not much difference between the two.

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

That may work well for the full documentation, but the quick reference 
wouldn't be a short quick reference any more.


I'm attempting to have a pydoc api call that gets a single item or sub-item 
and format it to a desired output so it can be included in other content. 
That's makes it possible for the full docs (not necessarily pythons) to 
embed pydoc output in it if it's desirable.  This will need pydoc 
formatters for the target document type.  I hope to include a reST output 
formatter for pydoc.

The help() function is imported from pydoc by site.py when you start 
python.  It may not be difficult to have it as a function that first tries 
pydoc to get a request, and if the original request is returned unchanged, 
tries to get information from the full documentation.  There could be a way 
to select one or the other, (or both).

But this feature doesn't need to be built into pydoc, or the full 
documentation.  They just need to be able to work together so things like 
this are possible in an easy to write 4 or 5 line function. (give or take a 
few lines)

So it looks like most of these issues are more a matter of how to organize 
the interfaces.  It turns out that what I've done with pydoc, and what 
Georg is doing with the main documentation should work together quite nicely.

Cheers,
    Ron