[Python-Dev] [isssue 2001] Pydoc enhancement patch questions

[Ron Adam]

This regards the following feature request.

     http://bugs.python.org/issue2001

Summery:

The pydoc "gui" enhancement patch adds a navigation bar on each page with 
features that correspond to abilities that are currently available to help. 
  ie.. a get field, to get help on an item, a find field, to search for 
modules by keyword, plus modules, topics, and keyword index links.

The file links read the python file in as text and inserts it into a web 
page instead of relying on the browser to do the right thing. (often enough 
it doesn't)

To achieve this I reworked the existing pydoc server into one that can 
respond to a navigation bar at the top of the served pages.  The new 
"local_text_server" will exist in the http package where the other server 
related modules are.  The callback function passed to the server does all 
the pydoc specific work so the server itself is a simple general purpose 
text server useful for making browser interface front ends.

This also removed the need for tkinter in pydoc and allows pydoc -g to work 
on computers where tk isn't installed.


As per discussion on the tracker:

> Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:
>
> +:program:`pydoc` :option:`-g` will start the server and additionally open a web
> +browser to a module index page.  Each served page has a navagation bar at the
> +top where you can 'get' help on a individual item, 'find' all modules with a
> +keyword in thier synopsis line, and goto indexes for 'modules', 'topics' and
> +'keywords'.
>
> I am not sure I like the fact that the browser is started automatically.
> Please bring this up on python-dev.  This may be an opportunity to
> rethink pydoc command line switches.  For example, -p and -g are
> currently exclusive, but it would make sense for -g to start server on
> the port specified by -p.

So are any thoughts on starting the web browser automatically, and on how 
the -g and -p command line switches work?

I'm also not sure about the name for the server.  I've use 
local_text_server, but it may also be useful in non-local cases as well.

The newest patch is...

      http://bugs.python.org/file18165/pydoc_server3.diff

Any feedback will be welcome.

Ron