[Python-Dev] Pydoc Improvements / Rewrite

Laurent Gautier lgautier at gmail.com
Fri Jan 5 11:01:22 CET 2007


Ron,

Thanks for your detailed answer.
I inserted comments below.

2007/1/5, Ron Adam <rrr at ronadam.com>:
> Laurent Gautier wrote:
[cut]
>
> > Introspection is probably already available in the separate module
> > 'inspect',
> > and what a code pydoc would have to do is model the documentation
> > (as a tree) and offer convenience function to navigate the data. Beside
> > that,
> > there would be sub-modules for the different viewers for the documentation
> > data - the interactive console being just one of the viewers.
>
> Pydoc currently uses functions from the inspect module along with directly
> accessing attributes and other information where it is available.  It's not a
> replacement for the inspect module.
>
> My first attempt used an xml tree to store the information, but to make that
> work requires also storing a fair amount of meta information in the tree as
> well.  I found parsing the tree and the meta information to be more complex than
> using an objective approach which is (to me) more readable and easier to extend.
>   But if you want to try it again, please do.  You may come up with something
> far better than I did.

Well, I was coining the idea from the understanding that the main split was
console viewer vs other viewer. I was thinking of something a design
along the lines of the Model-View-Presenter pattern.... and I guess
that you will have to
read your code if I want to debate on that ;-).

> > Finally, I would suspect that an API-breaking modification of the module
> > would
> > need time to be accepted.
>
> I was considering this for python 3.0, but one of the developers suggested it
> would be nice to have in python 2.6 and to move the discussion here.
>
> I think any API issues could be worked out.  Are there any programs you know of,
> (yours?), that import pydoc besides the python console?

What I did barely qualifies as a hack for my own usage -it won't count-.

>From the top of my head, there might be  "ipython" (the excellent
interactive console) is possibly using pydoc
(in any case, I would say that the authors would be interested in
developments with pydoc)

Otherwise a quick search lead to:
- "cgitb" (!? - it seems that the HTML formatting functions of pydoc
are only in use - wouldn't these functions belong more naturally to "cgi" ?)
- "DocXMLRPCServer" (hey ! it looks like kind-of what I was needing !!!).
- "happydoc" (reportedly having problems with python 2.4 - I am not
sure that it is maintained)

"cgitb" and "DocXMLRPCServer" are both distributed bundled with Python.

"cgitb" seems to be mostly using HTML formatting helpers (and that would
suggest the need for an HTML-rendering module - may be for a future
improvement,  a first step would be separate the rendering/viewing
from extraction and modeling of documentation data).

"DocXMLRPCServer" looks (at first sight), like a viewer that would be bundled
with pydoc as a sub-module (i.e., module in a package).


>
[cut:  Ka-Ping Yee <ping at lfw.org> is now in the loop]
>

> Pydoc is a fairly complex program and it would definitely help if others took a
> look at various parts and made contributions and or suggestions to making it better.

Well, I stumbled upon your recent posts in python-ideas (that I tracked up the
one in python-devel) because I looked into it I thought that it would be
a *lot* of work for one person.
(more on that in the next inlined comment)

> I may have also gotten a bit over my head, but I'm willing to stick it out and
> try to get it finished with any suggestions (and help) that any one is willing
> to give me.  There are also too many important issues for me to be decided, so
> this isn't something that can be done in isolation.
>
> The download link again is:
>
>      http://ronadam.com/dl/_pydoc.zip

I would be willing to help out, as probably others will as well (I
found blogs and
posts of people discussing pydoc, it might be worthwhile dropping a line to
the people - we can discuss that off-list if you wish), but may be at
one condition.

I do not think it will work as a zip file shuttled around (in my experience).
A versioning system would be extremely helpful (SVN, or CVS. would
come to my mind).
Well, if you are ok with having the source tree hosted in a
SVN/CVS/alike I am on
(opening an account on sourceforge or savannah -for example- would be
the next step then, as it can take few days for a project to be
approved)

> It's not fully functional yet, but does run. Some parts like the command line
> file output options still need to be reimplemented. Some output formatting still
> needs to be cleaned up, and the MRO tree parsing section still needs to be put
> back in.

I will have a look then.

>
> One question that I have at the moment is:
>
> * Would it be good to have the "KEYWORD" and "TOPICS" info as included data
> objects or files, and possibly use that to generate the python html (and other)
> documentation for these?  (Instead of the other way around like it is now.)
>
> This would eliminate the requirement to install something extra in order for
> help on these items to work.

I see that I was slow to write this email. I will read the following
before commenting  further.



L.


> > L.
> >
> > PS: I would also not go for a module name deliberately prefixed with "_"
> > (as some people might associate that with protected or private objects).
>
> The underscore was just a "temporary" convenience to avoid the name conflict
> with the existing module.  Weather to reuse the old name or use a new name is
> still one of the many open issues I think.
>
> Ron
>
>


More information about the Python-Dev mailing list