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

[Martin Blais]

Hi Ron
I haven't had time to check out your refactoring (too busy right now)
but I just wanted to mention that if there is anything from Haddoc
that you think you could salvage and would make sense to merge into
pydoc you're most welcome to do so.

Haddoc is a very simple python module and scripts that parse the HTML
doc indexes and then allows you to query for indexed terms and points
a browser to the search results.  There is a buddy elisp module for
accessing it from Emacs.
http://furius.ca/haddoc/

Just an idea.
cheers,





On 4/13/07, Ron Adam <rrr at ronadam.com> wrote:
>
> 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
>
>
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>