From srm_oracleunix at hotmail.com  Sun Apr  1 16:14:38 2007
From: srm_oracleunix at hotmail.com (SRM SRM)
Date: Sun, 01 Apr 2007 10:14:38 -0400
Subject: [Doc-SIG] add srm_oracleunix@hotmail.com
Message-ID: <BAY132-F1692272EE2A9ED780521CEE0610@phx.gbl>

An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/doc-sig/attachments/20070401/0cf83090/attachment.htm 

From rrr at ronadam.com  Thu Apr 12 22:06:01 2007
From: rrr at ronadam.com (Ron Adam)
Date: Thu, 12 Apr 2007 15:06:01 -0500
Subject: [Doc-SIG] PyDoc discussion
In-Reply-To: <se4po293ji.fsf@pc047299.dhcp.germanlloyd.org>
References: <se4po293ji.fsf@pc047299.dhcp.germanlloyd.org>
Message-ID: <461E9129.1080300@ronadam.com>


Would anyone here be interested in discussing details of the pydoc rewrite 
I've been working on?

And is this a good place for that?


Cheers,
    Ron Adam


From goodger at python.org  Fri Apr 13 15:02:22 2007
From: goodger at python.org (David Goodger)
Date: Fri, 13 Apr 2007 09:02:22 -0400
Subject: [Doc-SIG] PyDoc discussion
In-Reply-To: <461E9129.1080300@ronadam.com>
References: <se4po293ji.fsf@pc047299.dhcp.germanlloyd.org>
	<461E9129.1080300@ronadam.com>
Message-ID: <4335d2c40704130602s7fb55a31h974d4442c0dc04e5@mail.gmail.com>

On 4/12/07, Ron Adam <rrr at ronadam.com> wrote:
> Would anyone here be interested in discussing details of the pydoc rewrite
> I've been working on?

Yes, I would like to hear about it, and I think others would too.

> And is this a good place for that?

As good a place as any, I'd say ;-)
You may want to let python-dev & python-list know that a discussion is
happening here.

-- 
David Goodger <http://python.net/~goodger>

From rrr at ronadam.com  Fri Apr 13 17:15:40 2007
From: rrr at ronadam.com (Ron Adam)
Date: Fri, 13 Apr 2007 10:15:40 -0500
Subject: [Doc-SIG] Pydoc Rewrite Discussion at doc-sig list.
Message-ID: <461F9E9C.2070901@ronadam.com>


If anyone is interested in participating in discussing the details of the 
PyDoc rewrite/refactoring I've been working on, a discussion is being 
started on the doc-sig list.

	Doc-Sig at python.org

The goal of this discussion will be to get it to a final finished form so a 
patch can be submitted and a final discussion can take place on the 
python-dev list at a later date.

Thanks and Regards,
   Ron Adam

From rrr at ronadam.com  Fri Apr 13 17:18:23 2007
From: rrr at ronadam.com (Ron Adam)
Date: Fri, 13 Apr 2007 10:18:23 -0500
Subject: [Doc-SIG] PyDoc discussion
In-Reply-To: <4335d2c40704130602s7fb55a31h974d4442c0dc04e5@mail.gmail.com>
References: <se4po293ji.fsf@pc047299.dhcp.germanlloyd.org>	
	<461E9129.1080300@ronadam.com>
	<4335d2c40704130602s7fb55a31h974d4442c0dc04e5@mail.gmail.com>
Message-ID: <461F9F3F.7090408@ronadam.com>

David Goodger wrote:
> On 4/12/07, Ron Adam <rrr at ronadam.com> wrote:
>> Would anyone here be interested in discussing details of the pydoc 
>> rewrite
>> I've been working on?
> 
> Yes, I would like to hear about it, and I think others would too.

Great, I'll post a summery along with links to the SVN files today.


>> And is this a good place for that?
> 
> As good a place as any, I'd say ;-)
> You may want to let python-dev & python-list know that a discussion is
> happening here.

Done!  :-)

Cheers,
    Ron




From rrr at ronadam.com  Fri Apr 13 18:55:01 2007
From: rrr at ronadam.com (Ron Adam)
Date: Fri, 13 Apr 2007 11:55:01 -0500
Subject: [Doc-SIG] PYDOC Rewrite general description and files.
Message-ID: <evocl5$be9$1@sea.gmane.org>


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




From blais at furius.ca  Fri Apr 13 20:09:28 2007
From: blais at furius.ca (Martin Blais)
Date: Fri, 13 Apr 2007 11:09:28 -0700
Subject: [Doc-SIG] PYDOC Rewrite general description and files.
In-Reply-To: <evocl5$be9$1@sea.gmane.org>
References: <evocl5$be9$1@sea.gmane.org>
Message-ID: <8393fff0704131109s5ae0fa04o32b81aeeae3ad70a@mail.gmail.com>

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
>

From rrr at ronadam.com  Sun Apr 15 08:59:07 2007
From: rrr at ronadam.com (Ron Adam)
Date: Sun, 15 Apr 2007 01:59:07 -0500
Subject: [Doc-SIG] PYDOC Rewrite general description and files.
In-Reply-To: <8393fff0704131109s5ae0fa04o32b81aeeae3ad70a@mail.gmail.com>
References: <evocl5$be9$1@sea.gmane.org>
	<8393fff0704131109s5ae0fa04o32b81aeeae3ad70a@mail.gmail.com>
Message-ID: <4621CD3B.40305@ronadam.com>

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



From rrr at ronadam.com  Sun Apr 15 08:59:07 2007
From: rrr at ronadam.com (Ron Adam)
Date: Sun, 15 Apr 2007 01:59:07 -0500
Subject: [Doc-SIG] PYDOC Rewrite general description and files.
In-Reply-To: <8393fff0704131109s5ae0fa04o32b81aeeae3ad70a@mail.gmail.com>
References: <evocl5$be9$1@sea.gmane.org>
	<8393fff0704131109s5ae0fa04o32b81aeeae3ad70a@mail.gmail.com>
Message-ID: <4621CD3B.40305@ronadam.com>

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