PYDOC Rewrite general description and files.

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

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



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: PYDOC Rewrite general description and files.

Martin Blais-2
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 <[hidden email]> 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  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: PYDOC Rewrite general description and files.

Ron Adam
Martin Blais wrote:

> 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,

I'll look into it.  It does insert links to the on line python docs.  (I
just haven't put that part back in yet.)  I'll compare them and maybe your
script will do a more complete job.

Thanks,
    Ron


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig