[Doc-SIG] PYDOC Rewrite general description and files.

[Ron Adam]

The following is a general description of what I've done so far along with 
where you can view the files.

I hope after some general feedback has occurred we can focus on individual 
modules and get each one to a more robust and finished state.

Cheers,
    Ron




PyDoc refactoring general description
=====================================

This rewrite consist of modest improvements to the user interface of both
the interactive console and the web based interface, and fairly major
improvements to the organization and generality of the python routines.

The general approach taken is to make pydoc a useful toolbox of modules, 
class's and functions, so it can be used along with other documenting tools 
much more easily than the current module.  It is also important that the 
modules are easy to understand and maintain in the future.


The major points so far:
------------------------

     - Made it a package of usefull modules.
     - The console help is still pretty much the same.
     - The help() function returns a result string instead of printing it.
     - Removed the TK interface and implemented a more complete interactive
         html interface.
     - Some fairly nice improvements to the html output in general.
     - Uses a CSS stylesheet with generous tagging so that the html look
         can be customized quite extensivly by only changing the style
         sheet.
     - Developed a formatting framework so that custom output formatters can
         be written relatively easy.


Use's for pydoc in order of importance and frequency of use:
------------------------------------------------------------

     1. Console (builtin) help.  ie.. the help() function.
     2. HTML browsing and quick reference.
     3. Document generation in text.
     4. Document generation in html.
     5. Document generation in other formats.

Items 1 and 2 are the main priorty and are the parts I've concentrated on
until now.  The formatting framework will make writing scripts to generate 
output as files fairly easy. (I hope)

* After giving it much thought, it seems to me, that pydoc should not try
to read files and insert them into pydocs out put.  But rather, it
should be made easy to write scripts that get pydoc output and insert it
into files or templates.


The pydoc package contents:
---------------------------

     __init__.py     - imports (exports?) pyhelp.help() as pydoc.help so it
                     works in the console.

     pyhelp.py   - opens a text help session
       + pyhelp.help() - The interactive help function.
     gentext.py  - text formatter
     pager.py    - console pager


     pydoc.py    - Opens a web browser interface.
     genhtml.py  - Html formatter.
     defaultstyle.css - Css for html pages
     server.py   - A html server.  (generic, runs as a thread.)


     styledict.py - The DocInfo, Styledict, and Dispatcher classes.


     getinfo.py  - Handles requests and returns a DocInfo object.
     locate.py   - Finds and imports an object for introspection.


     index.py    - Returns a path/directory/package index object.
     find.py     - A filter for index requests... 'modules name' in text
                     session. (will accept web style requests)


     topics.py   - Pulls text from html docs.



Files can be viewed or downloaded from:
---------------------------------------

http://pydoc-r.svn.sourceforge.net/viewvc/pydoc-r/trunk/pydoc/


If you get the svn source, you can run pydoc.py and pyhelp.py as scripts.

Pyhelp.py will open an interactive help console session, and pydoc.py will
start a web server and open the browser to a module index.



Formatting / Dispatching tutorial:
----------------------------------

To understand how to the output formatting works I've written a doctest 
that is also a tutorial in styledict.py.

http://pydoc-r.svn.sourceforge.net/viewvc/pydoc-r/trunk/pydoc/styledict.py?view=markup