[stdlib-sig] pydoc enhancements

[Brett Cannon]

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

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