[stdlib-sig] pydoc enhancements

[Ron Adam]

Brett Cannon wrote:
> The deadline is for creating new packages, not adding to them. If a
> new module comes in and belongs in one of the new packages, adding is
> not a problem.
> 
> In other words you have nothing to worry about, Ron, unless you wanted
> to turn pydoc into a package or something.
> 
> -Brett

Good to know. Thanks.

Making it a package was discussed a while back with mixed results.

I think it doesn't need to be a package, but some of it's parts can be 
moved to other modules or packages.  For example the console pager section 
may be useful as part of the cmd package which is used to create 
interactive command interpreters.  And as mentioned, the server could be 
moved to the http package/module.  This patch should make those moves 
easier, so I think it's a good first step.

It's also makes it a handy tool to interactively browse the standard 
library in the process of reorganizing the standard library. ;-)

Ron



> On Wed, Mar 5, 2008 at 1:49 PM, Ron Adam <rrr at ronadam.com> wrote:
>>
>>  A few weeks ago I created a patch for pydoc which removes it's dependency
>>  on tk by adding a navigation bar to the top of the pages served to the browser.
>>
>>
>>  http://bugs.python.org/issue2001
>>
>>  The patch applies to python 2.6, but does not apply to 3.0 cleanly at this
>>  time. (Use the newest one, the older 2 patches can be deleted.)
>>
>>
>>
>>  To make these changes, the html server in pydoc was altered to be less
>>  independent on other parts of pydoc, ie.. more general use.  It's possible
>>  that this part could fit into http module.  This server serves generated
>>  strings instead of files.  Possibly SimpleHTTPServer should be
>>  SimpleHTTPFIleServer... or the py3k equivalent, http.server and
>>  http.fileserver?  The http file server could possibly subclass the http.server?
>>
>>
>>
>>
>>  Back to the PyDoc enhancements...
>>
>>  The served html page headers has a compact navbar that includes the
>>  following elements.
>>
>>      + The python version being used.
>>
>>      + A get field that accepts most things you would type at the
>>  interactive prompt.  This allows you to "get" a specific items docs without
>>   searching if you know the name.
>>
>>      + A search field that returns the same list as the "modules
>>  search_term" at interactive help prompt.  (or list all modules if no
>>  search_term is given.)
>>
>>      + An "index" link that returns the main module index page.
>>
>>      + A "keywords" and "topics" link that returns the same list as typing
>>  keywords or topics in interactive help.  And those links work if the html
>>  docs are installed.
>>
>>      + The "file" links on each pydoc page reads the *.py file in text mode
>>  and inserts the listing into an html page rather than relying on the
>>  browser to do the right thing with the file.  This is much much safer and
>>  personally I think this is a bug (poor design) that needs fixing.
>>
>>      + Starting "python -g" opens up the browser directly to the module
>>  index page. From there you can either click on a module in the index or use
>>  the added navbar header to get more specific help.
>>
>>
>>
>>  All of these enhancements make moving around in the browser and looking at
>>  python module docs very nice and easy.  No more switching back and forth
>>  between a tk control window and the browser.  I think it would be nice to
>>  have this in python 2.6 and later.
>>
>>  Note: The navbar header is not added to the generated html files as they
>>  won't use the same interactive server.
>>
>>
>>
>>  Unfortunately, I will be starting a trip tomorrow and will be away from my
>>  computer for a week to two weeks.  But I wanted to get this in before the
>>  14th idea deadline.  I will try to work on it more and include any
>>  suggestions when I get back, or maybe someone else would like to finish it
>>  up.  I think python docs will need to be updated.  Also it needs to be
>>  checked to be sure it works correctly across platforms/browsers.  There is
>>  currently no tests for the pydoc module although there is a file to
>>  manually check pydoc output in the Lib/test directory that could possibly
>>  be used to create a test with.
>>
>>
>>  Cheers,
>>     Ron
>