It's hard to find documentation
fperez528 at yahoo.com
Sat Dec 8 14:14:47 CET 2001
Brad Bollenbach wrote:
> I'm well aware of pydoc. Using your instructions on how to use it,
> we /still/ aren't able to locate the top-level document Bruce was
> interested in:
> mothra at mothra:~$ python2.1
> Python 2.1.1 (#1, Nov 11 2001, 18:19:24)
> [GCC 2.95.4 20011006 (Debian prerelease)] on linux2
> Type "copyright", "credits" or "license" for more information.
>>>> from pydoc import help
>>>> help("Extending and Embedding the Python Interpreter")
> no Python documentation found for 'Extending and Embedding the
> Python Interpreter'
You are right. pydoc isn't perfect yet, I think its indexing
algorithm still has room for a lot of improvement. But there's a
solid base to start from.
>>> If I wanted it badly enough, I would have done so already. :)
>> Ka-Ping Yee already did.
> Kudos to Ka-Ping Yee. He obviously wanted it more than I did, but it
> still doesn't provide the extreme ease of use (particularly for
> accessing top-level documents with minimal effort) that, for
> example, perldoc does. (That isn't a Perl plug, but the name "pydoc"
> implies that it wanted to be Python's equivalent of perldoc.)
Agreed. I love the html form of pydoc for module browsing, but I do
miss the ease of finding general info with perldoc. Another minor
gripe is that when running pydoc -g, the search box almost never
finds what I want (plus it's dog slow). I never use it, I just fire
it up so the server runs and then click my way through the top-level
So to summarize this whole discussion (maybe in the future someone
from the doc team can use this):
1) The 'search' at www.python.org is a perfectly useless piece of
junk. It would be better to remove the search option altogether and
just tell people to use google. Maybe in the future the 'ultraseek'
joke can be replaced with a site-local google.
2) Pydoc is great, but could stand improvement in its indexing/search
capabilities. Ideally, after a search it would return hierarchically
organized results (top-level docs, pages, modules, function
docstrings, etc). Returning this as a webpage (it already has a
server) would be great.
3) The written html docs are top-quality, but they lack a bit in
cross-referencing (though the general indices at the end of each are
*extremely* good). Fixing this is slow and time-consuming, and can
really only be done by someone who knows both python and the
documentation very well.
I think (1) should be very easy to fix (and should be a priority of
the site maintainers IMHO), (2) requires coding work but sounds like
a fairly interesting project. Moderately difficult, but not
impossible by any means. (3) I suspect will be the slowest to improve.
Just my thoughts,
More information about the Python-list