[Python-ideas] Improving Pydoc

[Brett Cannon]

On 12/22/06, Ron Adam <rrr at ronadam.com> wrote:
> Thomas Heller wrote:
> > Ron Adam schrieb:
> >> Improving pydoc has been suggested before by me and others.  I've been working
> >> on a version that is probably 80% done and would like to get feed back at this
> >> point to determine if I'm approaching this in the best way.
> >>
> >> Basically pydoc.py consists of over 2,000 lines of python code and is not well
> >> organized inside which means (my thoughts) it will pretty much stay the way it
> >> is and not be as useful as it could be.
> >>
> >> Currently pydoc.py has the following uses.
> >>
> >>      * It is imported and used as pythons console help function.
> >>      * It can be used to generate help text files.
> >>      * It can open a tkinter search index and from that launch a web server and
> >> a browser to veiw a html help page.
> >>      * It can be used to generate static html help files.
> >>
> >>
> >> It looks (to me) like splitting it into two modules would be good.  One module
> >> for just the text help and introspection functions, and the other for the html
> >> server and html output stuff.
> >
> > Yes, I remember several cases where I had to copy code out of pydoc.py because I wanted
> > to reuse it and could not because pydoc pulls in too much stuff (I care about this when
> > freezing my programs with py2exe).
> > Is splitting pydoc into 2 modules sufficient, or should it even be split into an own package?
>
> That is one of the questions I have, which would be preferable.  Here's a list
> of files I have and what they do.
>
> pyhelp.py        - Command line option parser / front end
> gettext.py       - Generates text output
> scanner.py       - module and search functions
> _pydoc.py        - starts server and web browser
> gethtml.py       - Generate html output
> server.py        - html server
> pager.py         - multy-platform console text pager
> stringtools.py   - frequently used string formatting functions
> stylesheet.css
>
> There is still quite a bit of inter-dependence between these, but not anywhere
> near as complex as the original was. I think you will need to look at the source
> to see what is actually going on though. I'll be posting a link to it either
> today or tomorrow.
>

I do like your idea of splitting the screen pager and the HTML aspect,
Ron.  And yes, pydoc needs a cleanup.

>
> > Although I do not believe that this is on-topic for *this* list; I would prefer
> > such changes to go into Python 2.6 already.
>
> As Brett said, and Guido promoted by asking for volunteers:
>
> On 12/18/06, Brett Cannon <brett at python.org> wrote:
>
>  > A Python pie-in-the-sky list (python-ideas?) seems reasonable.  Let's
>  > python-dev focus on maintaining the current code, python-3000 on
>  > Py3K-specific work, and the ideas list to be where new ideas are vetted out
>  > and congealed into a PEP to bring to either python-3000 or python-dev.
>
>
> While we could hash out the exact meaning of 'pie-in-the-sky', 'new-ideas',
> 'vetted out and congealed', etc...  my general impression is that things that
> aren't ready yet for python-dev or python-3000 should be here until they are
> ready.  Then of course, it could be moved to python-dev if you prefer.  I would
> like that too.
>
> This give us a place where we can have in progress discussion of features and
> *alternatives* without disrupting python-dev or python-3000 with things that
> aren't ready.
>
> In this case, there is still a lot more this needs before it's ready I think.  A
> PEP?  A fully (or mostly) working patch?  But maybe if others take an interest
> here, it won't be here long. ;-)
>

I don't view code cleanup as something for this list.  I view stuff
like "I want to hash out an idea on abstract base classes" and the
ilk.  Code reorganization, etc. that are more software engineering and
completely new idea should still go to python-dev or python-3000.
Basically stuff where people might throw a fit over the idea should
probably come here until it is a solid idea.  =)

So I agree with Thomas; this should go to python-dev.

-Brett