Python Documentation?

[Daniel R. Smorey Jr.]

I'm looking for a good place for Python documentation. I'm really lost
on why it's so hard to find anything when it comes to me looking up a
particular function in Python. My example would be the split() function
of the string module. Why can't I just go to www.python.org and click
on Search and then type in split and it bring me to the split() function
of the string module? Why does it have to be so hard? This is what I
get when I search for split on www.python.org...

http://search.python.org/query.html?qt=split&col=ftp&col=python&col=peps&col=starship

Most of those hits are for the re module, not the string module (which
in my opinion should be part of python and not a module, but I digress).
Why would it not bring up the split function of the string module
first and foremost?

If I do a search right now on www.perldoc.com for split, I get...

http://www.perldoc.com/cgi-bin/htsearch?words=split&restrict=perl5.8.0

Right there, the top hit is the slit function, how convenient.

If I go to www.php.net and type in split in the function list search, I
get...

http://www.php.net/manual/en/function.split.php

I don't even get a hit list, it goes right to the split() function.
Even more convenient.

I'm trying to learn Python because we're doing some work on the Zaurus
and there are so many supporting python modules for the Zaurus, that I'd
like to use it. I love learning new languages also. It just gives me a
bad taste in my mouth when I even think of searching for anything in Python.

Am I searching the wrong place? Am I choosing the wrong checkboxes on
the Search page? I'm at a loss. Is it really that hard to find
documentation on the python.org site?

Thanks for hearing my rant and I'm hoping I'm just doing something
wrong. I really can't imagine such an organized programming language
having such a horrible search on their website.

[Robert Kern]

Re: Python Documentation?

In article <LQydncwLlNp2 UM-iXTWJkA@comcast .com>,
"Daniel R. Smorey Jr." <smory@ptdprolo g.net> writes:[color=blue]
> I'm looking for a good place for Python documentation. I'm really lost
> on why it's so hard to find anything when it comes to me looking up a
> particular function in Python. My example would be the split() function
> of the string module. Why can't I just go to www.python.org and click
> on Search and then type in split and it bring me to the split() function
> of the string module?[/color]

Well, since you know which module the function is in, you can go to the
documentation page, look up string in the Global Module Index and find
split(). Only a few more clicks.

Or, even easier, you can fire up the interpreter, and do the following:
[color=blue][color=green][color=darkred]
>>> import string
>>> help(string.spl it)[/color][/color][/color]

Or, on the commandline, type

pydoc string.split
[color=blue]
> Why does it have to be so hard? This is what I
> get when I search for split on www.python.org...
>
> http://search.python.org/query.html?...s&col=starship
>
> Most of those hits are for the re module, not the string module (which
> in my opinion should be part of python and not a module, but I digress).[/color]

Most of them are since 2.0. Check out string methods.

http://python.org/doc/current/lib/string-methods.html

[color=blue]
> Why would it not bring up the split function of the string module
> first and foremost?[/color]

Because no one has asked for it to do so before? Because the unpaid
volunteers with limited time who run the site don't need the feature
themselves and never realized that others might want it? Because the
string method and re function split() are equally good or better options
to return first?

Although I agree that there should be a checkbox option to search only
the current docs.

--
Robert Kern
kern@caltech.ed u

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

[John Burton]

Re: Python Documentation?

"Daniel R. Smorey Jr." <smory@ptdprolo g.net> wrote in message
news:LQydncwLlN p2UM-iXTWJkA@comcast .com...[color=blue]
> I'm looking for a good place for Python documentation. I'm really lost
> on why it's so hard to find anything when it comes to me looking up a
> particular function in Python. My example would be the split() function[/color]

The help within python itsself is a good start.
For your example try

import string
help(string.spl it)

No need to visit a web site.

[Steven Taschuk]

Re: Python Documentation?

Quoth Daniel R. Smorey Jr.:[color=blue]
> I'm looking for a good place for Python documentation. I'm really lost
> on why it's so hard to find anything when it comes to me looking up a
> particular function in Python. My example would be the split() function
> of the string module. [...trouble searching for it at python.org...][/color]

For full-text searches, try <http://www.pydoc.org/>.

For functions and whatnot, there's the index of the Library
Reference, <http://www.python.org/doc/2.3/lib/genindex.html>.

[...][color=blue]
> Most of those hits are for the re module, not the string module (which
> in my opinion should be part of python and not a module, but I digress).[/color]

Indeed, in sufficiently recent Pythons (2.0+, I think), split() is
a method of string objects:[color=blue][color=green][color=darkred]
>>> 'foo bar'.split()[/color][/color][/color]
['foo', 'bar']
Likewise for many other functions in the string module.

(This method is the second hit for "split" at pydoc.org, and is
listed in the Library Reference index.)

--
Steven Taschuk "The world will end if you get this wrong."
staschuk@telusp lanet.net -- "Typesettin g Mathematics -- User's Guide",
Brian Kernighan and Lorrinda Cherry

[Nick Welch]

Re: Python Documentation?

pydoc is pretty nice, try "pydoc str", and then use / to search for
"split".

As far as searching the online docs, it takes a little adaptation. To
look for str.split, I'd do a google "site:www.python.org built-in
types", and then look for str, and then look at split.

And doing just that, and clicking once or twice, brought me to:

http://www.python.org/doc/current/lib/string-methods.html

Although I agree, it would be cool if the online documentation supported
such direct search methods as e.g. www.php.net/split.

--
Nick Welch aka mackstann | mack @ incise.org | http://incise.org
What is the difference between a Turing machine and the modern
computer? It's the same as that between Hillary's ascent of Everest
and the establishment of a Hilton on its peak.

[Chad Netzer]

Re: Python Documentation?

On Sun, 2003-08-31 at 21:41, Daniel R. Smorey Jr. wrote:[color=blue]
> Why can't I just go to www.python.org and click
> on Search and then type in split and it bring me to the split() function
> of the string module?[/color]

Not a bad idea.
[color=blue]
> Why does it have to be so hard?[/color]

Start up a python interpreter and type:

help('string.sp lit')

To see the whole string module:

help('string')

It also work directly on module and function objects:

import string
help(string)

Finally, the string module is being slowly phased out. You can use the
string constructor type instead (in Python 2.2 and later):

help(str.split)
help(str)
etc...

--
Chad Netzer

[Dan Thrue]

Re: Python Documentation?

Daniel R. Smorey Jr. wrote:[color=blue]
> I'm looking for a good place for Python documentation. I'm really lost
> on why it's so hard to find anything when it comes to me looking up a
> particular function in Python. My example would be the split() function
> of the string module. Why can't I just go to www.python.org and click
> on Search and then type in split and it bring me to the split() function
> of the string module? Why does it have to be so hard? This is what I
> get when I search for split on www.python.org...
>
> http://search.python.org/query.html?...s&col=starship
>
>
> Most of those hits are for the re module, not the string module (which
> in my opinion should be part of python and not a module, but I digress).
> Why would it not bring up the split function of the string module first
> and foremost?
>
> If I do a search right now on www.perldoc.com for split, I get...
>
> http://www.perldoc.com/cgi-bin/htsea...rict=perl5.8.0
>
> Right there, the top hit is the slit function, how convenient.
>
> If I go to www.php.net and type in split in the function list search, I
> get...
>
> http://www.php.net/manual/en/function.split.php
>
> I don't even get a hit list, it goes right to the split() function. Even
> more convenient.
>
> I'm trying to learn Python because we're doing some work on the Zaurus
> and there are so many supporting python modules for the Zaurus, that I'd
> like to use it. I love learning new languages also. It just gives me a
> bad taste in my mouth when I even think of searching for anything in
> Python.
>
> Am I searching the wrong place? Am I choosing the wrong checkboxes on
> the Search page? I'm at a loss. Is it really that hard to find
> documentation on the python.org site?
>
> Thanks for hearing my rant and I'm hoping I'm just doing something
> wrong. I really can't imagine such an organized programming language
> having such a horrible search on their website.
>[/color]


Hi Daniel,

Me and a friend am about to finish a project in a couple of weeks, that
maybe fits your needs.

We are currently documenting the parts if python, we meet in our daily
python development (Some gaming software where we mix native delphi with
python. This mixture has surprised us a lot, we are indeed python
fanatics now, hehe).

The documentation takes contributions on example snippets, description,
etc. so when the site is completely done and a base of documentation
have been posted, im gonna post link in here, then maybe the community
will help us to create a great documentation source :) And find the
errors we might post :)

Regards all,
Dan

[Larz]

Re: Python Documentation?

> The documentation takes contributions on example snippets,[color=blue]
> description, etc. so when the site is completely done and a base of
> documentation have been posted, im gonna post link in here, then maybe
> the community will help us to create a great documentation source :)[/color]

Hi all, I'm the friend that Dan is talking about ;)

Just wanted to clarify our project a little bit.

Dan and I are long time php programmers. One thing that is superb about
php, is it's online documentation that everyone in the community can
contribute to (not the actual documentation, just comments with
examples).

Every since I first started using python, I've truly missed a
documentation source similar to that of PHP's. So Dan and I have started
our little project to make a documentation site in the spirit of that
documentation.

So far it looks great, and you can see some python documentation by using
URLs like http://example.com/doc/string.split and there will of course be
a search function.

Also, it will not only be the "standard" modules of Python, by suggestion
(and perhaps permission), we will include third party modules, such as
MySQLdb and the like.

As Dan writes, it will be ready very soon, within a few weeks. It will of
course be devoid of user comments in the beginning, but we're hoping that
users will contribute with some of their invaluable experience!



Best regards,

Lars Petersen

--
larz
to mail me, remove your pants!

[Cameron Laird]

Re: Python Documentation?

In article <Xns93E975FCE1E 58godlarz@62.24 3.74.162>,
Larz <lp@your-pants-coder.dk> wrote:

[Michael Hudson]

Re: Python Documentation?

"Daniel R. Smorey Jr." <smory@ptdprolo g.net> writes:
[color=blue]
> I'm looking for a good place for Python documentation.[/color]

In addition to what others said, there's Thomas Heller's pyhelp.cgi
thingy:

http://starship.python.net/crew/theller/pyhelp.cgi

and Mark Hammond's Mozilla sidebar:

http://starship.python.net/crew/mhammond/mozilla/index.html

(which provides an interface to Thomas' script).
[color=blue]
> I'm really lost on why it's so hard to find anything when it comes
> to me looking up a particular function in Python. My example would
> be the split() function of the string module.[/color]

You mean you weren't born knowing what that did? Sheesh, kids these
days... <wink>.

Cheers,
mwh

--
Never meddle in the affairs of NT. It is slow to boot and quick to
crash. -- Stephen Harris
-- http://home.xnet.com/~raven/Sysadmin/ASR.Quotes.html

[Dan Thrue]

Re: Python Documentation?

Cameron Laird wrote:[color=blue]
> In article <Xns93E975FCE1E 58godlarz@62.24 3.74.162>,
> Larz <lp@your-pants-coder.dk> wrote:
> .
> .
> .
>[color=green]
>>Dan and I are long time php programmers. One thing that is superb about
>>php, is it's online documentation that everyone in the community can
>>contribute to (not the actual documentation, just comments with
>>examples).
>>
>>Every since I first started using python, I've truly missed a
>>documentati on source similar to that of PHP's. So Dan and I have started
>>our little project to make a documentation site in the spirit of that
>>documentation .[/color]
>
> .
> .
> .
> PHP's documentation has indeed been a great success as a
> collaborative adventure.
>
> Python already has a structure--and much content!--for
> comparable collaboration in <URL: http://
> www.python.org/cgi-bin/moinmoin/ >. Moreover, as several
> follow-ups have explained, Python developers have differ-
> ent work practices than PHPers, and a different relation
> to documentation. In particular, it's hard to overempha-
> size how much working Python programmers depend on
> interactive introspection: use of the interpreter's
> built-in help, pydoc, and related facilities to discover
> and confirm details that, in PHPonia, are regarded as
> matters for online documentation.[/color]

Hi Cameron,

Thank for your feedback, i personally uses pydoc when im in need of
documentation, but sometimes i have been in such situations where code
snippets was necessary for me. The background for this project is to
gain a great database public of snippets hooked in a structure that is
easily for all to use, novice as well as expert.

Maybe its the way i think, but i understand and learn a lot faster
(better?) when the the theory is put into practice.

At my daily work im a .net programmer, and the documentation im using
there is also "practice based". Im not a theoretic person, and I think
there is a lot like myself out there :)

Best Regards
Dan

[Larz]

Re: Python Documentation?

claird@lairds.c om (Cameron Laird) wrote in news:vl6dmm8jut l140
@corp.supernews .com:
[color=blue]
> Python already has a structure--and much content!--for
> comparable collaboration in <URL: http://
> www.python.org/cgi-bin/moinmoin/ >. Moreover, as several
> follow-ups have explained, Python developers have differ-
> ent work practices than PHPers, and a different relation
> to documentation. In particular, it's hard to overempha-
> size how much working Python programmers depend on
> interactive introspection: use of the interpreter's
> built-in help, pydoc, and related facilities to discover
> and confirm details that, in PHPonia, are regarded as
> matters for online documentation.[/color]

Yes, I agree that a lot of python programmers think differently.
Even though, I sense a general consensus, especially among beginning
Pythoneers, that the community lacks a great tool, like the one PHP has.
Of course I am not just thinking about the documentation itself, which you
could get with pydoc/help(), but also experience, pointers, pitfalls that
other people ran in to. That's what makes it a community ;)

Anyway, I am pretty sure we're going to fill a much needed niche, and if
not, we're certainly going to meet our own needs ;)

--
larz
to mail me, remove your pants!

[Cameron Laird]

Re: Python Documentation?

In article <Xns93E99702FBA BCgodlarz@62.24 3.74.162>,
Larz <lp@your-pants-coder.dk> wrote:[color=blue]
>claird@lairds. com (Cameron Laird) wrote in news:vl6dmm8jut l140
>@corp.supernew s.com:
>[color=green]
>> Python already has a structure--and much content!--for
>> comparable collaboration in <URL: http://
>> www.python.org/cgi-bin/moinmoin/ >. Moreover, as several
>> follow-ups have explained, Python developers have differ-
>> ent work practices than PHPers, and a different relation
>> to documentation. In particular, it's hard to overempha-
>> size how much working Python programmers depend on
>> interactive introspection: use of the interpreter's
>> built-in help, pydoc, and related facilities to discover
>> and confirm details that, in PHPonia, are regarded as
>> matters for online documentation.[/color]
>
>Yes, I agree that a lot of python programmers think differently.
>Even though, I sense a general consensus, especially among beginning
>Pythoneers, that the community lacks a great tool, like the one PHP has.
>Of course I am not just thinking about the documentation itself, which you
>could get with pydoc/help(), but also experience, pointers, pitfalls that
>other people ran in to. That's what makes it a community ;)
>
>Anyway, I am pretty sure we're going to fill a much needed niche, and if
>not, we're certainly going to meet our own needs ;)[/color]

[Cameron Laird]

Re: Python Documentation?

In article <3f533f3d$0$324 67$edfadb0f@dre ad16.news.tele. dk>,
Dan Thrue <rummanddan_nos pam@hotmail.com > wrote:[color=blue]
>Cameron Laird wrote:[color=green]
>> .
>> .
>> .
>> Python already has a structure--and much content!--for
>> comparable collaboration in <URL: http://
>> www.python.org/cgi-bin/moinmoin/ >. Moreover, as several[/color][/color]

[Dan Thrue]

Re: Python Documentation?

Cameron Laird wrote:[color=blue]
> In article <3f533f3d$0$324 67$edfadb0f@dre ad16.news.tele. dk>,
> Dan Thrue <rummanddan_nos pam@hotmail.com > wrote:
>[color=green]
>>Cameron Laird wrote:
>>[color=darkred]
>>> .
>>> .
>>> .
>>>Python already has a structure--and much content!--for
>>>comparable collaboration in <URL: http://
>>>www.python.org/cgi-bin/moinmoin/ >. Moreover, as several[/color][/color]
>
> .
> .
> .
>[color=green]
>>Thank for your feedback, i personally uses pydoc when im in need of
>>documentation , but sometimes i have been in such situations where code
>>snippets was necessary for me. The background for this project is to
>>gain a great database public of snippets hooked in a structure that is
>>easily for all to use, novice as well as expert.[/color]
>
> .
> .
> .
> I apologize for muddling my message. I completely agree
> that a public knowledge store of code fragments and re-
> lated matters, that is easy for all to access, is a great
> blessing. That's the aim of the Wiki. Or were you
> judging the Wiki a failure in that, but too polite to
> make it explicit?[/color]

No i wont judge anything a failure in this community :) To say it
shortly, the wiki doesnt actually fill my requirements.

Hope that isnt an too arrogant attitude I put up, but remember we do
this effort for the community as well for our selves.

Best regards,
Dan