subject:"python documentation"

On Sat, Mar 27, 2021 at 4:20 PM  wrote:
>
> Chris,
>
> you seem to imply, that I have compiled said versions without reason and
> that the same would be possible on basis of Python 3 - which is simply
> not true. Maybe you are not enough acquainted with Qt and belonging
> libraries alike PyQtGraph. Maybe you are just not willing to see /
> accept these arguments.
>
> By the way, some months ago I started trying to migrate to Python 3 and
> gave up in favor of creating said compilation. Compatibility of Python
> and its Packages decreased with V3 significantly. A whole lot of minor
> and major incompatibilities between your subversions and belonging
> packages. This was one reason, why Java took the route to its own death.

FUD. Lots and lots of FUD. More reasons to not promote your
distribution. Use it if you will, but it doesn't merit any further
visibility.

> With a view to the mid and long term future, this discussion even gives
> me cause to ponder about whether it doesn't make more sense to rely more
> on C# and WinForms for professional projects from now on. I am fluent in
> both too and it always makes sense to bet on the right horse at an early
> stage.

If you prefer, go for it. Everyone claims that it's easier to move to
 rather than to migrate to Python 3, and I'm
calling people's bluffs now. Go ahead and move to another language if
it's easier - it's no skin off my nose.

Or maybe it isn't easier, and that's just an empty argument. Funny how
it keeps coming up.

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation


Chris,

you seem to imply, that I have compiled said versions without reason and 
that the same would be possible on basis of Python 3 - which is simply 
not true. Maybe you are not enough acquainted with Qt and belonging 
libraries alike PyQtGraph. Maybe you are just not willing to see / 
accept these arguments.


By the way, some months ago I started trying to migrate to Python 3 and 
gave up in favor of creating said compilation. Compatibility of Python 
and its Packages decreased with V3 significantly. A whole lot of minor 
and major incompatibilities between your subversions and belonging 
packages. This was one reason, why Java took the route to its own death.


With a view to the mid and long term future, this discussion even gives 
me cause to ponder about whether it doesn't make more sense to rely more 
on C# and WinForms for professional projects from now on. I am fluent in 
both too and it always makes sense to bet on the right horse at an early 
stage.


But to be honest, I see no reason to discuss that further, you seem to 
be quite determined - so be it. Ignore Blythooon. I have no disadvantage 
by that, as I would not have an advantage the other way round, so I am 
fine with it.


Best Regards
Dominik






On 2021-03-27 04:44, Chris Angelico wrote:

On Sat, Mar 27, 2021 at 2:15 PM  wrote:


No, I am not encouraging, I am just offering the possibility.

Python and its community once was not dogmatic. At least this was my
impression when I started - after all Python originally had been
designed to be multi paradigmatic. This spirit of freedom was one 
mayor

reason for Python to grow so fast - from my POV.

But freedom is constituted by freedom of choice.

It might be a good thing to recommend people to switch to Python 3.*, 
it

might be a bad idea to FORCE people to do so by taking away the
possibility to install Python 2.7.*; some people tend to react badly
when infantilised.


Why do you install 2.7.18? Isn't it a bad idea to FORCE people onto
that particular version, instead of letting them run 2.7.9 or 2.7.1 if
they choose? Does it infringe on their freedoms by offering only one
version?

If people want a specific version, they can get it. There's no reason
to promote the use of outdated versions.


If I am right, the Python 2.7.* installers still are provided on the
python.org website. So long as this is done, I cannot see a reason not
to list a 'distribution' using Python 2.7.* in said list, right?


You have a pre-1.0 distribution of an end-of-life version of Python
that works on a very specific platform. That's fine. But there's no
reason to have it promoted anywhere.


By the way, there is more, Blythooon offers beyond what I already have
written in the last email. Otherwise please name me another comparable
MINIMAL 'distribution', which is compiled specifically for scientific
FRONTend development? In terms of diversity I also cannot see, why
Blythooon MUST have something special to be listed? Is it not enough,
that it is another one?



Nope, not enough for it to be promoted. The page you linked to
originally is a very short list of only those which are notable enough
to be worth promoting. And from what I'm seeing, yours isn't.

Move to Python 3 and leave the old version behind. It has been a year
since Python 2 received any updates at all, and over a decade since
2.7 was originally released. Isn't it time it was finally permitted to
rest in peace?

ChrisA

--
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation

2021-03-26 Thread MRAB


On 2021-03-27 03:44, Chris Angelico wrote:

On Sat, Mar 27, 2021 at 2:15 PM  wrote:



[snip]

By the way, there is more, Blythooon offers beyond what I already have
written in the last email. Otherwise please name me another comparable
MINIMAL 'distribution', which is compiled specifically for scientific
FRONTend development? In terms of diversity I also cannot see, why
Blythooon MUST have something special to be listed? Is it not enough,
that it is another one?



Nope, not enough for it to be promoted. The page you linked to
originally is a very short list of only those which are notable enough
to be worth promoting. And from what I'm seeing, yours isn't.

Move to Python 3 and leave the old version behind. It has been a year
since Python 2 received any updates at all, and over a decade since
2.7 was originally released. Isn't it time it was finally permitted to
rest in peace?


It's not dead; it's just pining for the fjords. :-)
--
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation

On Sat, Mar 27, 2021 at 2:15 PM  wrote:
>
> No, I am not encouraging, I am just offering the possibility.
>
> Python and its community once was not dogmatic. At least this was my
> impression when I started - after all Python originally had been
> designed to be multi paradigmatic. This spirit of freedom was one mayor
> reason for Python to grow so fast - from my POV.
>
> But freedom is constituted by freedom of choice.
>
> It might be a good thing to recommend people to switch to Python 3.*, it
> might be a bad idea to FORCE people to do so by taking away the
> possibility to install Python 2.7.*; some people tend to react badly
> when infantilised.

Why do you install 2.7.18? Isn't it a bad idea to FORCE people onto
that particular version, instead of letting them run 2.7.9 or 2.7.1 if
they choose? Does it infringe on their freedoms by offering only one
version?

If people want a specific version, they can get it. There's no reason
to promote the use of outdated versions.

> If I am right, the Python 2.7.* installers still are provided on the
> python.org website. So long as this is done, I cannot see a reason not
> to list a 'distribution' using Python 2.7.* in said list, right?

You have a pre-1.0 distribution of an end-of-life version of Python
that works on a very specific platform. That's fine. But there's no
reason to have it promoted anywhere.

> By the way, there is more, Blythooon offers beyond what I already have
> written in the last email. Otherwise please name me another comparable
> MINIMAL 'distribution', which is compiled specifically for scientific
> FRONTend development? In terms of diversity I also cannot see, why
> Blythooon MUST have something special to be listed? Is it not enough,
> that it is another one?
>

Nope, not enough for it to be promoted. The page you linked to
originally is a very short list of only those which are notable enough
to be worth promoting. And from what I'm seeing, yours isn't.

Move to Python 3 and leave the old version behind. It has been a year
since Python 2 received any updates at all, and over a decade since
2.7 was originally released. Isn't it time it was finally permitted to
rest in peace?

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation


No, I am not encouraging, I am just offering the possibility.

Python and its community once was not dogmatic. At least this was my 
impression when I started - after all Python originally had been 
designed to be multi paradigmatic. This spirit of freedom was one mayor 
reason for Python to grow so fast - from my POV.


But freedom is constituted by freedom of choice.

It might be a good thing to recommend people to switch to Python 3.*, it 
might be a bad idea to FORCE people to do so by taking away the 
possibility to install Python 2.7.*; some people tend to react badly 
when infantilised.


If I am right, the Python 2.7.* installers still are provided on the 
python.org website. So long as this is done, I cannot see a reason not 
to list a 'distribution' using Python 2.7.* in said list, right?


By the way, there is more, Blythooon offers beyond what I already have 
written in the last email. Otherwise please name me another comparable 
MINIMAL 'distribution', which is compiled specifically for scientific 
FRONTend development? In terms of diversity I also cannot see, why 
Blythooon MUST have something special to be listed? Is it not enough, 
that it is another one?


But, in the end, this naturally is not my decision.

Cheers, Dominik







On 2021-03-26 22:57, Chris Angelico wrote:

On Sat, Mar 27, 2021 at 7:49 AM  wrote:


Hi Chris,


thank you for your interest and thanks for asking.


Blythooon is notable due to several reasons; let's compare it with 
some

of the already listed (and thus obviously notable) 'distributions':

2) winpython seems not to support Python 2.7.* anymore.

Blythooon supports Python 2.7.18.



Ah. That is indeed notable, but not in a good way. You are encouraging
the use of an end-of-life version of Python, and your installer has
very little to boast beyond that.

ChrisA

--
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation

On Sat, Mar 27, 2021 at 7:49 AM  wrote:
>
> Hi Chris,
>
>
> thank you for your interest and thanks for asking.
>
>
> Blythooon is notable due to several reasons; let's compare it with some
> of the already listed (and thus obviously notable) 'distributions':
>
> 2) winpython seems not to support Python 2.7.* anymore.
>
> Blythooon supports Python 2.7.18.
>

Ah. That is indeed notable, but not in a good way. You are encouraging
the use of an end-of-life version of Python, and your installer has
very little to boast beyond that.

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation - addendum

Sorry, copy & paste obviously failed, here is the link I wanted to 
include:


https://www.anaconda.com/terms-of-service



On 2021-03-26 17:33, Chris Angelico wrote:

On Sat, Mar 27, 2021 at 3:31 AM  wrote:


Howdy Folks,


I would like to suggest adding "Blythooon" to the list under "Other
parties have re-packaged CPython" listed here:



What makes it notable?

ChrisA

--
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation


Hi Chris,


thank you for your interest and thanks for asking.


Blythooon is notable due to several reasons; let's compare it with some 
of the already listed (and thus obviously notable) 'distributions':


1) pythonxy seems not to be maintained anymore - the last version I 
found is from 2015.


Blythooon is still maintained and the last version is from February 
2021.



2) winpython seems not to support Python 2.7.* anymore.

Blythooon supports Python 2.7.18.


3) When using Anaconda Python you might not only have to respect the 
anaconda/miniconda licenses but also the terms of service of the 
belonging website. For commercial uses that might pose some problems. If 
you have a peek into the text:


https://www.python.org/download/alternatives/

You may find statements alike "we are not granting you permission to use 
the Repository for commercial activities" or "Your use of the Repository 
is at the sole discretion of Anaconda, which may deny you further use of 
the Repository or terminate this license at any time, for any reason, 
with or without cause." there... Companies tend to have problems with 
this :)


Blythooon is a netinstaller which downloads from python.org and 
pypi.org. No comparable limitations are known to me for these sources.



4) Blythooon is not a distribution in the original sense; it is a 
netinstaller, which is able to download, (md5-)check and install a 
'snapshot' of packages/versions:


   - Python 2.7.18
   - Virtualenv 20.2.2
   - PySide 1.2.2
   - NumPy 1.16.6
   - PyQtGraph 0.10.0
   - Matplotlib 2.2.5
   - SciPy 1.1.0
   - PySerial 3.5
   - Pyadaaah 0.90

and some further packages supporting said ones. This compilation has 
been carefully assembled to allow the development of advanced, 
production quality, scientific, Python 2.7 applications with Qt 4.8 
based GUIs and the ability to display nice (live) plots (via PyQtGraph 
and/or Matplotlib). Blythooon obviously comes with some mathematical 
stuff alike NumPy or SciPy too.


Said versions work together well. The developer does not need to find 
out, which versions work together well. Because that is not easy. Try 
e.g. PyQtGraph 0.11.* with PySide 1.2.* - you might be
disappointed then, as well as if you would be trying PyQtGraph 0.10.* 
with PySide 1.2.4.


All Blythooon installations, if not manually modified, are 100% 
compatible, as I said, it is more a 'snapshot' then a permanently 
self-updating distribution... Blythooon does not focus on up-to-dateness 
but on proven stability and compatibility. But, as Blythooon sets up a 
Python Runtime Environment just based on PIP, the developer naturally 
can tailor his installation further (e.g. by installing further packages 
or upgrading the existing).


Blythooon is a (nearly fully) automatic netinstaller for Windows 10 only 
(at least yet, depending on the feedback, porting to Linux / macOS could 
be done easily - the netinstaller is based on the platform independent 
powershell).



I hope, some aspects are notable enough...


Best Regards
Dominik










On 2021-03-26 17:33, Chris Angelico wrote:

On Sat, Mar 27, 2021 at 3:31 AM  wrote:


Howdy Folks,


I would like to suggest adding "Blythooon" to the list under "Other
parties have re-packaged CPython" listed here:



What makes it notable?

ChrisA

--
https://mail.python.org/mailman/listinfo/python-list

Re: python documentation

On Sat, Mar 27, 2021 at 3:31 AM  wrote:
>
> Howdy Folks,
>
>
> I would like to suggest adding "Blythooon" to the list under "Other
> parties have re-packaged CPython" listed here:
>

What makes it notable?

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

python documentation


Howdy Folks,


I would like to suggest adding "Blythooon" to the list under "Other 
parties have re-packaged CPython" listed here:



https://www.python.org/download/alternatives/



Blythooon can be found here:

https://pypi.org/project/blythooon/

and the belonging installation step-by-step-guide video here:

https://www.youtube.com/channel/UCOE8xqYS_2azFsFjBVEwVMg



May I ask - how can I do that best? Thanks in advance and


Best Regards
Dominik
--
https://mail.python.org/mailman/listinfo/python-list

Official Python documentation lookup while programming (was: Is the content available in the html doc available in help()?)

2016-09-17 Thread Ben Finney

Peng Yu  writes:

> Hi, I want to get the same content as the html doc from help().

That's not what the ‘help’ function does, so I don't think that's
feasible.

Moreover, the Python interpreter does not have any notion of where the
HTML documentation is stored, nor how to access it, nor how to present
it.

So no, a Python interactive prompt does not natively have a way to do
what you're asking.

What you may like is to get your programming environment to present the
official Python documentation as part of that environment.

For example, the documentation is rendered to GNU Info format and
available to install from https://github.com/politza/python-info>,
which makes it immediately available in Info readers, such as the one
native to Emacs.

-- 
 \   “If you ever fall off the Sears Tower, just go real limp, |
  `\ because maybe you'll look like a dummy and people will try to |
_o__)catch you because, hey, free dummy.” —Jack Handey |
Ben Finney

-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Python Documentation Improvement

2014-11-25 Thread Steven D'Aprano

Archana Pandey wrote:

[...]
> A = a + 1 and a += 1  both behave in same way for all data types except
> python Lists

I cannot think of any other mutable data type that supports + but there are
mutable data types that support other augmented assignment operators:

py> a = set("abcd")
py> b = a  # now b and a both point to the same set
py> a -= set("cat")
py> print b
set(['b', 'd'])

To understand this behaviour, you have to understand three facts:

(1) Assignment is name-binding, not copying. So when you say "b = a", that
makes "b" another name for the same object as "a", not a copy of "a".

(2) Augmented assignments like += -= &= etc. are not just permitted but
*encouraged* to use in-place modification with mutable types such as list
and set.

(3) The standard operators + - & etc. are expected to create new objects,
not modify the existing object.

That should explain the difference in behaviour between regular assignment
and augmented assignment.

[...]
> NOTE: Documentation should provide sufficient information for such
> scenario.

Personally, I think that the documentation is clear enough, but I welcome
suggestions for improvement. Can you point us to the parts of the
documentation which you think are not clear enough? Do you have some
suggested improvements?

-- 
Steven

-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Python Documentation Improvement

2014-11-25 Thread Mark Lawrence


On 25/11/2014 11:44, Archana Pandey wrote:

Hello

I hereby would like to share the problem I have faced regarding python
list implementation :-

As per python documentation python list is mutable data object.

The problem I found with the list is that is behaves differently when we
use ‘+=’ and ‘+’  ‘=’ operators separately.

For example-

A = a + 1 and a += 1  both behave in same way for all data types except
python Lists

Please find the attached module and execute it on windows python32, See
the difference in output.

NOTE: Documentation should provide sufficient information for such scenario.



Patches are always welcome on the bug tracker.  I observe that you 
already know the way :)


--
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence

--
https://mail.python.org/mailman/listinfo/python-list

Python Documentation Improvement

2014-11-25 Thread Archana Pandey

Hello

 I hereby would like to share the problem I have faced regarding python
list implementation :-

 As per python documentation python list is mutable data object.

The problem I found with the list is that is behaves differently when we
use ‘+=’ and ‘+’  ‘=’ operators separately.

For example-

A = a + 1 and a += 1  both behave in same way for all data types except
python Lists

Please find the attached module and execute it on windows python32, See the
difference in output.

NOTE: Documentation should provide sufficient information for such scenario.

Kind Regards

Archana Pandey


Operator_bug_python.py
Description: Binary data
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Where to suggest improvements in the official Python documentation?

2013-08-20 Thread Joel Goldstick

On Tue, Aug 20, 2013 at 10:22 AM, Aseem Bansal  wrote:
> @Joel Goldstick
>> Joel Goldstick
>>
>> http://joelgoldstick.com
>
> My specific question was that the Python documentation's tutorial isn't clear 
> when it comes to lambda forms. I just wanted something to be done so it 
> becomes clear for future readers who are not familiar with functional 
> paradigm. I wanted to make a suggestion about adding a link to functional 
> programming to add some clarity.

In my first post above I provided the link for bug reports for python
(including documentation).  This is a volunteer list which is not
officially part of the python.org site.  You might try going to that
link to learn how to submit change requests.
> --
> http://mail.python.org/mailman/listinfo/python-list



-- 
Joel Goldstick
http://joelgoldstick.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Where to suggest improvements in the official Python documentation?

2013-08-20 Thread Aseem Bansal

@Joel Goldstick
> Joel Goldstick
> 
> http://joelgoldstick.com

My specific question was that the Python documentation's tutorial isn't clear 
when it comes to lambda forms. I just wanted something to be done so it becomes 
clear for future readers who are not familiar with functional paradigm. I 
wanted to make a suggestion about adding a link to functional programming to 
add some clarity.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Where to suggest improvements in the official Python documentation?

2013-08-04 Thread Joel Goldstick

On Sun, Aug 4, 2013 at 12:30 PM, Aseem Bansal  wrote:
> @ Terry Jan Reedy
>
> If there is an issue in place for improving the lambda forms then that's 
> good. I wanted a link about functional programming because it is mentioned as 
> if it were a household word.

It depends on your household I suppose!

Have you tried google?

I am having a hard time understanding what your specific question is.
Do you have one?
> --
> http://mail.python.org/mailman/listinfo/python-list



-- 
Joel Goldstick
http://joelgoldstick.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Where to suggest improvements in the official Python documentation?

2013-08-04 Thread Aseem Bansal

@ Terry Jan Reedy

If there is an issue in place for improving the lambda forms then that's good. 
I wanted a link about functional programming because it is mentioned as if it 
were a household word.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Where to suggest improvements in the official Python documentation?

2013-08-03 Thread Terry Reedy


On 8/3/2013 2:23 PM, Joel Goldstick wrote:

On Sat, Aug 3, 2013 at 1:53 PM, Aseem Bansal 
wrote:

I have a suggestion about the Python tutorial for improvement.
Specifically about in Python tutorial 4.7.5 lambda forms.
http://docs.python.org/3/tutorial/controlflow.html#lambda-forms

It is not very clear from the tutorial what lambda forms are for


They are mostly for passing a one-use function as an argument to another 
function. The tutorial should say that and give an example.


http://bugs.python.org/issue18646


someone who doesn't know functional programming. I think placing a
link of "functional Programming HOWTO" of Python documentation can
take out much confusion for Python newbies.


That document is not about lambda. The word 'lambda' does not appear 
until near the end, and some of the current examples violate PEP 8.



I would like to suggest this because as I newbiw I had much
confusion 2 months back before I could figure out its proper use.
Where do I suggest this improvement? --



http://docs.python.org/2/bugs.html


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Where to suggest improvements in the official Python documentation?

2013-08-03 Thread Joel Goldstick

On Sat, Aug 3, 2013 at 1:53 PM, Aseem Bansal  wrote:
> I have a suggestion about the Python tutorial for improvement. Specifically 
> about in Python tutorial 4.7.5 lambda forms.
> http://docs.python.org/3/tutorial/controlflow.html#lambda-forms
>
> It is not very clear from the tutorial what lambda forms are for someone who 
> doesn't know functional programming. I think placing a link of "functional 
> Programming HOWTO" of Python documentation can take out much confusion for 
> Python newbies.
>
> I would like to suggest this because as I newbiw I had much confusion 2 
> months back before I could figure out its proper use. Where do I suggest this 
> improvement?
> --
> http://mail.python.org/mailman/listinfo/python-list

http://docs.python.org/2/bugs.html

-- 
Joel Goldstick
http://joelgoldstick.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Where to suggest improvements in the official Python documentation?

2013-08-03 Thread Aseem Bansal

I have a suggestion about the Python tutorial for improvement. Specifically 
about in Python tutorial 4.7.5 lambda forms.
http://docs.python.org/3/tutorial/controlflow.html#lambda-forms

It is not very clear from the tutorial what lambda forms are for someone who 
doesn't know functional programming. I think placing a link of "functional 
Programming HOWTO" of Python documentation can take out much confusion for 
Python newbies.

I would like to suggest this because as I newbiw I had much confusion 2 months 
back before I could figure out its proper use. Where do I suggest this 
improvement?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Problems with Python documentation [Re: Don't feed the troll...]

2013-06-17 Thread Joel Goldstick

On Mon, Jun 17, 2013 at 6:50 PM, Steven D'Aprano <
steve+comp.lang.pyt...@pearwood.info> wrote:

> On Mon, 17 Jun 2013 07:41:54 -0700, rurpy wrote:
>
> > On 06/17/2013 01:23 AM, Chris Angelico wrote:
> >> On Mon, Jun 17, 2013 at 3:04 PM, Ferrous Cranus 
> >> wrote:
> >>> The only thing i'm feeling guilty is that instead of reading help
> >>> files and PEP's which seem too technical for me, i prefer the live
> >>> help of an actual expert human being.
> >>
> >> This is definitely a reason to feel guilty. You are asking people to
> >> provide live help for free, rather than simply reading the
> >> documentation.
> >
> > It is NOT a matter of simply reading the documentation. I have posted
> > here several times as have many others about some of the problems the
> > documentation has, especially for people who don't already know Python.
>
> This is very reasonable. And nobody -- well, at least not me, and
> probably not Chris -- expects that reading the documentation will
> suddenly cause the light to shine for every beginner who reads it. Often
> the official docs are written with an expected audience who already knows
> the language well.
>
> But in context, Nikos has been programming Python long enough, and he's
> been told often enough, that his FIRST stop should be the documentation,
> and us second. Not what he does now, which is to make us his first,
> second, third, fourth, fifth, sixth, seventh and eighth stops.
>
> (Are you paying attention Nikos?)
>
> But speaking more generally, yes, you are right, the docs are not a
> panacea. If they were, mailing lists like this, and websites like
> StackOverflow, would not exist.
>
>
>
I read the python docs.  I've gone through the tutorials.  If not the first
time, or the second, I get that Aha moment with additional reads.  Some
people say they learn better by other methods than reading.  In that case,
google like crazy because python has lots of pycon stuff online in video
form, and there is the google course.  and many others.  If people
interaction is what you need, find, and visit your local meetup or user
group.  Lots of places have them.  If you don't have one near you, maybe
you could start one so you would have local help and back and forth
(fourth?).  I think its great to read a question here and get a link for an
answer.  gives me somewhere to go explore more.  If you reject these ways
of learning for the single method of asking.. fix my code.  Then you will
never get good at this craft anyway.  Its not the answers that are
important, its discovering how to find the answers that is really
important.  The old give a man a fish, vs teach a man to fish truism




-- 
Joel Goldstick
http://joelgoldstick.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Problems with Python documentation [Re: Don't feed the troll...]

2013-06-17 Thread Steven D'Aprano

On Mon, 17 Jun 2013 07:41:54 -0700, rurpy wrote:

> On 06/17/2013 01:23 AM, Chris Angelico wrote:
>> On Mon, Jun 17, 2013 at 3:04 PM, Ferrous Cranus 
>> wrote:
>>> The only thing i'm feeling guilty is that instead of reading help
>>> files and PEP's which seem too technical for me, i prefer the live
>>> help of an actual expert human being.
>> 
>> This is definitely a reason to feel guilty. You are asking people to
>> provide live help for free, rather than simply reading the
>> documentation.
> 
> It is NOT a matter of simply reading the documentation. I have posted
> here several times as have many others about some of the problems the
> documentation has, especially for people who don't already know Python.

This is very reasonable. And nobody -- well, at least not me, and 
probably not Chris -- expects that reading the documentation will 
suddenly cause the light to shine for every beginner who reads it. Often 
the official docs are written with an expected audience who already knows 
the language well.

But in context, Nikos has been programming Python long enough, and he's 
been told often enough, that his FIRST stop should be the documentation, 
and us second. Not what he does now, which is to make us his first, 
second, third, fourth, fifth, sixth, seventh and eighth stops.

(Are you paying attention Nikos?)

But speaking more generally, yes, you are right, the docs are not a 
panacea. If they were, mailing lists like this, and websites like 
StackOverflow, would not exist.

-- 
Steven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: PyDoc - Python Documentation Plugin for Eclipse

2012-06-15 Thread Alexey Gaidamaka

On Sun, 10 Jun 2012 15:37:50 +, Alexey Gaidamaka wrote:

> On Sun, 10 Jun 2012 05:02:35 -0500, Andrew Berg wrote:
> 
>> On 6/10/2012 4:22 AM, Alexey Gaidamaka wrote:
>>> Practically the plugin  is a simple html archive from python
>>> documentation website running
>>> inside Eclipse so you can call it using Eclipse help system. As for
>>> now it is pretty large (~7 mb), but i'm planning to optimize it in
>>> near future.
>> Rather than archive documentation, why not use a simple static page
>> that points to the different sections for each version of Python on
>> docs.python.org? The 2.7.3 documentation is mostly useless to me since
>> I'm using 3.3 (and of course there are some using 2.6 or 3.2 or
>> 3.1...), but I can easily access it from a link in the page you've
>> archived. Not only would this reduce the size of the plugin to almost
>> nothing, but it would prevent the documentation from being outdated.
>> 
>>> For more information, please visit:
>>> https://sourceforge.net/projects/pydoc/
>> Why isn't it installed like other Eclipse plugins? Is it even possible
>> to update the plugin via Eclipse?
>> 
>> 
>> This does look like a very useful plugin, though. Great idea.
> 
> Thanx! All that you've mentioned is planned in the next versions of the
> plugin.

http://pydoc.tk/news.html

TBD: 

1. updating and installing plugin through standard Eclipse "work with..." 
dialogue
2. reduce size of the original plugin that utilizes static content

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: PyDoc - Python Documentation Plugin for Eclipse

2012-06-15 Thread Alexey Gaidamaka

On Sun, 10 Jun 2012 12:14:15 +0300, Alexey Gaidamaka wrote:

> Greets!
> 
> Since i'm new to Python, i've decided to create a handy plugin for
> Elipse SDK which is my primary dev environment. Practically the plugin 
> is a simple html archive from python documentation website running
> inside Eclipse so you can call it using Eclipse help system. As for now
> it is pretty large (~7 mb), but i'm planning to optimize it in near
> future.
> 
> For more information, please visit:
> 
> http://pydoc.tk/
> 
> or
> 
> https://sourceforge.net/projects/pydoc/
> 
> 
> Advices are appreciated!
> 
> Contact e-mail: 
> 
> ahaidam...@gmail.com 

Hi there again!

I've made up some minor changes in plugin. Now it works with online 
documentation from docs.python.org and supports online doc for 2.6, 2.7, 
3.2, 3.3. Plugin weights around 8KB because all the static content was 
deleted.

Additional infos are here: http://pydoc.tk/news.html

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: PyDoc - Python Documentation Plugin for Eclipse

2012-06-10 Thread Alexey Gaidamaka

On Sun, 10 Jun 2012 05:02:35 -0500, Andrew Berg wrote:

> On 6/10/2012 4:22 AM, Alexey Gaidamaka wrote:
>> Practically the plugin  is a simple html archive from python
>> documentation website running
>> inside Eclipse so you can call it using Eclipse help system. As for now
>> it is pretty large (~7 mb), but i'm planning to optimize it in near
>> future.
> Rather than archive documentation, why not use a simple static page that
> points to the different sections for each version of Python on
> docs.python.org? The 2.7.3 documentation is mostly useless to me since
> I'm using 3.3 (and of course there are some using 2.6 or 3.2 or 3.1...),
> but I can easily access it from a link in the page you've archived. Not
> only would this reduce the size of the plugin to almost nothing, but it
> would prevent the documentation from being outdated.
> 
>> For more information, please visit:
>> https://sourceforge.net/projects/pydoc/
> Why isn't it installed like other Eclipse plugins? Is it even possible
> to update the plugin via Eclipse?
> 
> 
> This does look like a very useful plugin, though. Great idea.

Thanx! All that you've mentioned is planned in the next versions of the 
plugin.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: PyDoc - Python Documentation Plugin for Eclipse

2012-06-10 Thread Andrew Berg

On 6/10/2012 4:22 AM, Alexey Gaidamaka wrote:
> Practically the plugin  is a simple html archive from python
> documentation website running
> inside Eclipse so you can call it using Eclipse help system.
> As for now it is pretty large (~7 mb), but i'm planning to optimize it
> in near future.
Rather than archive documentation, why not use a simple static page that
points to the different sections for each version of Python on
docs.python.org? The 2.7.3 documentation is mostly useless to me since
I'm using 3.3 (and of course there are some using 2.6 or 3.2 or 3.1...),
but I can easily access it from a link in the page you've archived. Not
only would this reduce the size of the plugin to almost nothing, but it
would prevent the documentation from being outdated.

> For more information, please visit:
> https://sourceforge.net/projects/pydoc/
Why isn't it installed like other Eclipse plugins? Is it even possible
to update the plugin via Eclipse?


This does look like a very useful plugin, though. Great idea.
-- 
CPython 3.3.0a3 | Windows NT 6.1.7601.17790


-- 
http://mail.python.org/mailman/listinfo/python-list

PyDoc - Python Documentation Plugin for Eclipse

2012-06-10 Thread Alexey Gaidamaka


Greets!

Since i'm new to Python, i've decided to create a handy plugin for 
Elipse SDK which is my primary dev environment.
Practically the plugin  is a simple html archive from python 
documentation website running

inside Eclipse so you can call it using Eclipse help system.
As for now it is pretty large (~7 mb), but i'm planning to optimize it 
in near future.


For more information, please visit:

http://pydoc.tk/

or

https://sourceforge.net/projects/pydoc/


Advices are appreciated!

Contact e-mail: 
 
ahaidam...@gmail.com 


-- 
http://mail.python.org/mailman/listinfo/python-list

PyDoc - Python Documentation Plugin for Eclipse

2012-06-10 Thread Alexey Gaidamaka


Greets!

Since i'm new to Python, i've decided to create a handy plugin for 
Elipse SDK which is my primary dev environment.
Practically the plugin  is a simple html archive from python 
documentation website running

inside Eclipse so you can call it using Eclipse help system.
As for now it is pretty large (~7 mb), but i'm planning to optimize it 
in near future.


For more information, please visit:

http://pydoc.tk/

or

https://sourceforge.net/projects/pydoc/


Advices are appreciated!

Contact e-mail: 
 
ahaidam...@gmail.com 


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-04 Thread News123

On 11/02/2010 02:42 PM, Steven D'Aprano wrote:

> However, there is a Python wiki. It doesn't get anywhere near as much 
> love as it deserves, and (I think) the consensus was that the official 
> Python docs should stay official, but link to the wiki for user-
> contributed content. This hasn't happened yet.
> 
> http://wiki.python.org/moin/

That sounds like an excellent idea.
I often would have appreciated more examples or discussions about a
given module/class/function without having to fall back to Google.

It might be a good compromise:

clearly separating official doc and examples, but accepting, that the
doc is often insufficient without digging into the sources or searching
for more xamples.

The more one uses python, the easier it becomes to find what one looks for.

My first Impression about Python however was:
- the basic language is rather easy to learn
- the library documentation was more difficult to understand than the
one for PHP or for Perl.

> Frankly, I think that the best thing you could do is start a fork of the 
> docs and see if you get any interest from people. If you do, then you can 
> go back to python-dev with proof that there is a genuine popular desire 
> for more structured, PHP-style documentation.

I'd prefer crosslinking the doc with something, that's easier for
beginners of for people who never used a given library before.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-04 Thread Lawrence D'Oliveiro

In message , Cameron 
Simpson wrote:

> But its weakness is stuff like this:
> 
>   http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html
> 
> Automatic docness, no useful information.

But it Conforms to Documentation-Production Metrics as decreed by the 
Corporate Task Force on Policy. So long as the divisions are satisfying the 
official metrics on documentation production, that must mean the project is 
meeting its goals.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-03 Thread Martin Gregorie

On Thu, 04 Nov 2010 08:03:37 +1100, Cameron Simpson wrote:

> On 02Nov2010 04:23, jk  wrote: | This
> (http://epydoc.sourceforge.net/stdlib/) is what I'm talking | about.
> |
> | Why aren't the official docs like this, and why has it taken me 2 days
> | of searching? All this needs is a search engine behind it and it'd be
> | perfect.
> 
> It looks a lot like javadoc. But its weakness is stuff like this:
> 
>   http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html
> 
> Automatic docness, no useful information.
>
You get the same problem in Java and it has exactly the same root: a lazy 
programmer who can't be arsed to document his code.
 

-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org   |
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-03 Thread Cameron Simpson

On 02Nov2010 04:23, jk  wrote:
| This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
| about.
| 
| Why aren't the official docs like this, and why has it taken me 2 days
| of searching? All this needs is a search engine behind it and it'd be
| perfect.

It looks a lot like javadoc. But its weakness is stuff like this:

  http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html

Automatic docness, no useful information.

And of course the ugliness; I find the python docs much nicer to look
at. But I do wish the cross referencing was a bit better, often.
-- 
Cameron Simpson  DoD#743
http://www.cskk.ezoshosting.com/cs/

In an insane society, the sane man must appear insane.
- Keith A. Schauer 
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-03 Thread Cameron Simpson

On 02Nov2010 03:42, jk wrote:
| I've been coding in PHP and Java for years, and their documentation is
| concise, well structured and easy to scan.

While I agree about Java, at least the core Java docs, and javadoc
output in general (_great_ cross referencing!) I have mixed feelings
about the PHP docs. Though I suspect that stems from a dislike of the
PHP library API in general more than the docs, perhaps.

| Others have mentioned this apparently for years (see:
|
http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851
| and http://www.russellbeattie.com/blog/python-library-docs-still-suck
| and http://xahlee.org/perl-python/xlali_skami_cukta.html).
|
| Compare for instance the differences in ease of use, and speed of use,
| of these:
|
| http://docs.python.org/library/functions.html#open
| http://uk.php.net/manual/en/function.fopen.php
|
| The former is difficult to find (try searching for 'open' in the
| search box and see what you get).

I confess I almost never use the search box - as you say the result
relevance can be dodgy.

However, I do find the docs easy to use and pleasant to read on the
whole. My use is as follows:

For speed and convenience I have the docs locally stored.

I open the front page and then usually both the modules and index in
adjacent brwoser tabs.

I go to the index if I'm not sure of the module.

The strength of the index is that it tends to contain stuff that people
thought should be indexed (versus searches, which often have no
contextual understanding of the text, so their relevance is weaker).
The weakness of the index is that it can be hard to pick the relevant
entry. Open-link-in-new-tab is my friend here:-(

| It is simply a collection of
| paragraphs without strong enough contrast to differentiate the
| different parts - parameters, parameter values, return types,
| exceptions and related functions. It is slow to read and doesn't allow
| easy visual scanning.

That is true (the scanning). But by contrast, it does read like prose
and lends itself to a visit that gets you a complete feel for the
function.

[...]
| Has anyone else struggled while trying to learn the language? The
| whole documentation system seems geared towards people who already
| know what they're looking for and is close to useless for beginners.
| I'm not the only one who finds google an easier way to find
| documentation about python.

I certainly don't find the core docs hard to use (with some exceptions;
I still don't really understand the urllib stuff for the cases where
configuration is needed - weird proxy setups etc).

I've only been using Python for a few years and have generally found
that language easy to learn and the docs easy to read. I rarely reach
for The Google unless I'm seeking examples; the docs could do with a few
more of these IMHO.

I understand the attraction of the structured layout javadoc yields but
find it leads to "drier" documentation. It also works well for Java
because it is strongly typed - a great deal of the structure in the docs
can come directly from the code because argument counts, names and types
are always explicit (or deducable).

These are just initial responses. Now to wade the whole thread:-)
--
Cameron Simpson DoD#743
http://www.cskk.ezoshosting.com/cs/

On the contrary of what you may think, your hacker is fully aware
of your company's dress code. He is fully aware of the fact that it
doesn't help him to do his job.
- Gregory Hosler
--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-03 Thread Hallvard B Furuseth

Steven D'Aprano writes:
> On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote:
>> The former is difficult to find (try searching for 'open' in the search
>> box and see what you get).
>
> A fair point -- the built-in open comes up as hit #30, whereas searching 
> for open in the PHP page brings up fopen as hit #1. But the PHP search 
> also brings up many, many hits -- ten pages worth.
>
> But in any case, the Python search functionality could be smarter. If I 
> had a complaint about the docs, that would be it. Fortunately, I have 
> google :)

Actually that was one of the hair-tearing attitudes I heard a web search
guru complain about.  The smartest part of the search engine is the
people running it, so why not apply their brains directly?  Read the log
like you did, look for poor results (like "open"), put in exceptions by
hand.  This might be a fraction of the work it takes to program that
kind of smarts into the engine.  Or you might discover a group of
exceptions to put in - like all Python keywords.  That makes it at least
partially programmed, which may be preferable.

-- 
Hallvard
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-03 Thread jk

On Nov 2, 11:06 pm, Lawrence D'Oliveiro  wrote:
> In message
> , jk
> wrote:
>
> > This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> > about.
>
> Framesets? Is that really your idea of well-laid-out documentation? Using a
> feature which has been derided (and dropped in HTML5) because of its effect
> on usability and accessibility?

No, the framesets suck, and I agree that Javadoc isn't perfect.
Actually, I do think the PHP docs are the best I've found as a
reference. Javadocs just need a few tweaks and they'd be better (an
index at the top so you don't have to scroll down, no framesets, a
search engine). Still think they're better than the python docs though.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-03 Thread Lawrence D'Oliveiro

In message , Dennis Lee 
Bieber wrote:

> Whereas I have a whole shelf of Java documentation and it still
> takes me an hour to write "Hello World"... Java's one class per file
> results in a plethora of bloody names one has to remember just to find
> out where to start looking for a standard library operation.

You know Alan Kay’s dictum that “simple things should be simple, and complex 
things should be possible”?

Well, Java isn’t designed to make simple things simple. :)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread rantingrick


AD i agree with you! The official python tutorial and the official
docs are pretty much a twisted mass of confusion to the initiated
programmer. Even today when i try yo search the docs i find the result
quite frankly useless. And the search reminds me of the old XP "puppy
dog" search.  The doc ARE fairly well written HOWEVER the search
engine needs an update.

For me, i just Google it, and forget it!
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread John Bond



My 2c:

I use the ActiveState distro, and it's winhelp doco. It's generally ok 
and some things, like Dive Into Python, I've found excellent.


But I do quite regularly find myself cursing at the vagueness of the 
index, and some of the content seems to require that you know it before 
you read it (I wish I could remember an example).


Like everything, it could be improved.

Cheers, JB



--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Lawrence D'Oliveiro

In message <2010110223050345181-nizum...@mcnuggetscom>, Nizumzen wrote:

> On 2010-11-02 10:42:22 +, jk said:
> 
>> I've been coding in PHP and Java for years, and their documentation is
>> concise, well structured and easy to scan.
> 
> Are you mad? Javadoc is one of the worst examples of source code
> documentation I can possibly imagine.

It appeals to corporate herds of code-cutter drones, though. It follows 
tedious rules that can be officially adopted as corporation policy, and 
cited as a conformance feature by third-party products that these 
corporations seem happy to spend money on. So the comments can be extracted 
from the code, sorted, collated, stamped, filed, indexed, and collated 
again, all as part of the make-work activity that seems to pass for actual 
productivity in so many big corporations.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Kee Nethery


> 
>> 
>> Therefore, if you truly want changes in the documentation, I suggest that,
>> rather then whining to the group, you make some of the changes yourself.
> 
> I agree up to here, with a different interpretation of the last clause.
> Work within the existing system. There are currently 250 open doc issues on 
> the tracker at bugs.python.org.

wow, a backlog of 250. Either 250 is the weekly submittal amount and they get 
dealt with within a week, OR the backlog is months old and the bug system is 
not an effective way to get changes or enhancements to the documentation. 
Either way, 250 open doc issues gives me the feeling that the existing 
documentation system is not working for the people trying to use it.

> After registering, go to the search page
> http://bugs.python.org/iss...@template=search&status=1
> select Components: Documentation and hit Return (or [Search])
> 
> Find an issue that is waiting for someone to suggest a new or replacement 
> sentence or paragraph, and make one. No .diff patch required, just put it in 
> the message. Or look at existing suggestions and comment.

Given that newbies are the ones who run into these issues and have a great 
desire to spare others the pain they have suffered trying to learn Python, and 
newbies typically do not know about the bug tracking system as the way to 
request enhancements to the docs (that's not how wikipedia and other sites do 
changes to information), perhaps it would be useful to put a link to a page 
that explains how to improve the docs, on each doc page? 

I have to agree with others. My preferred Python documentation is either the 
books I have, or a search on Google. A google search typically has several 
postings from people on non-official sites with the exact same confusion I 
have, and what they have tried and what ultimately worked. The suggestion was 
made that people create their own documentation if they don't like the official 
documentation, and that does seem to be a good source for python documentation.

Kee Nethery


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread James Mills

On Wed, Nov 3, 2010 at 9:05 AM, Nizumzen  wrote:
> Are you mad? Javadoc is one of the worst examples of source code
> documentation I can possibly imagine. I would go as far to say that the
> Python guys should do exactly the opposite of Javadoc.

For what it's worth, I concur.

cheers
James


-- 
-- James Mills
--
-- "Problems are solved by method"
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread AD.

On Nov 3, 7:43 am, Tim Harig  wrote:
> On 2010-11-02, jk  wrote:
>
> > As for the 9 paragraphs statement, there's a usability book that
> > applies here - it's called "Don't make me think". I shouldn't have to
>
> Anything that promotes a lack of thinking sends up red flags in my head.
> We want to recruit smart people who think, not idiots.

"Don't make me think" is the UI equivalent of "There should be one and
preferably only one obvious way to do it". Not about advocating no
thinking, but about reducing the amount of unimportant decisions you
require your users to make. But I don't think the book specifically
addresses Dutch users though.

Back on topic - I do like the Python docs overall. Especially compared
to the PHP docs. I like the overall look and format of the new Sphinx
generated ones too.

My only criticism is that the content can sometimes be a little too
terse/concise. It's fine for experienced developers, but in some
places a little more explanation and/or examples would help out the
less experienced. I can usually figure out how to do something
eventually, but the docs for some modules take more deciphering than
others.

--
Cheers
Anton
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Lawrence D'Oliveiro

In message 
, jk 
wrote:

> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.

Framesets? Is that really your idea of well-laid-out documentation? Using a 
feature which has been derided (and dropped in HTML5) because of its effect 
on usability and accessibility?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Nizumzen


On 2010-11-02 10:42:22 +, jk said:


Hi,

I've been coding in PHP and Java for years, and their documentation is
concise, well structured and easy to scan.


Are you mad? Javadoc is one of the worst examples of source code 
documentation I can possibly imagine. I would go as far to say that the 
Python guys should do exactly the opposite of Javadoc.


--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Terry Reedy


On 11/2/2010 2:43 PM, Tim Harig wrote:


The real question is what do you want to gain by your posts here.  You
should already know that most groups are, by their very nature, slow to
make changes to the status quo.  The problem tends to be exasperated in
open source projects where any changes mean that people have to donate
their time to make anything happen.  You will in general find two things to
be true:

1. Since they are dontating their time, you will find that people tend to
scratch their own iches first.

2. People who do take the time to contribute to open source projects are
people of action.  They don't tend to be appreciative of those who
constantly generate feature requests but have no inclination to do
any of the work themselves.  They do appreciate other people of
action who are interested in making the project better.

Therefore, if you truly want changes in the documentation, I suggest that,
rather then whining to the group, you make some of the changes yourself.


I agree up to here, with a different interpretation of the last clause.
Work within the existing system. There are currently 250 open doc issues 
on the tracker at bugs.python.org.


After registering, go to the search page
http://bugs.python.org/iss...@template=search&status=1
select Components: Documentation and hit Return (or [Search])

Find an issue that is waiting for someone to suggest a new or 
replacement sentence or paragraph, and make one. No .diff patch 
required, just put it in the message. Or look at existing suggestions 
and comment.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread John McMonagle

On 03/11/10 05:04, John Nagle wrote:

>Right.  Google does a far better job of organizing Python's
> documentation than the Python community does.  I don't even try
> looking up anything starting at Python.org; I always start
> with a Google search.  Even though Python.org's search is
> powered by Google, it's inferior to a general search.
> 
>Compare:
> 
> http://www.google.com/search?domains=www.python.org&sitesearch=www.python.org&q=open
> 
> 
> http://www.google.com/search?q=Python+open
> 


Even better:


http://www.google.com/search?sitesearch=docs.python.org&q=open


Regards,

John McMonagle
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Man pages and info pages (was: Python documentation too difficult for beginners)

2010-11-02 Thread Tim Harig

On 2010-11-02, Tim Harig  wrote:
> On 2010-11-02, Teemu Likonen  wrote:
>> With the text terminal info browser called "info" as well as Emacs' info
>> browser you can use command "s" (stands for "search"). It prompts for a
>> regexp pattern to search in the whole document, including subsections
>> etc.
>
> Right, pinfo offers this as well; but, then you have to figure out where in
> the nodes that the search has taken you and how to navigate from that node
> to find additional information that you may need.  I have, in general, come
> to think of info pages as a failed experiment and I know very few people
> who actually prefer them over the simpler man pages.

I should add two more things here:

1. Another confusing aspect of the info pages is that you often have to
know what package a command came from or you don't get the
information that you are looking for.

2. Series of man pages can be used in a way that seem like they have a
structure as they can effectively link to other pages.  If I open
one of the ncurses man pages in pinfo, I can follow what seem like
links to other man pages.  I can open the main curses page and I
effectively get an index to all of the other curses functions.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Man pages and info pages (was: Python documentation too difficult for beginners)

2010-11-02 Thread Tim Harig

On 2010-11-02, Teemu Likonen  wrote:
> * 2010-11-02 18:43 (UTC), Tim Harig wrote:
>
>> The manual format contains all of the information on one page that can
>> be easily searched whereas the info pages are split into sections that
>> must be viewed individually. With the man pages, you can almost always
>> find what you want with a quick search through the document. Info
>> pages are much harder to use because you have to try and figure out
>> which section the author decided to place the information that you are
>> looking for.
>
> There is also the problem that people are less familiar with info
> browsers than the usual "less" pager which is used by "man" command.

I thoroughly agree.  The default info viewers are quite possibly the most
counterintuitive programs I have ever encountered.  I never did bother to
learn how to use them.  I instead installed the more intuitive pinfo
program.

> With the text terminal info browser called "info" as well as Emacs' info
> browser you can use command "s" (stands for "search"). It prompts for a
> regexp pattern to search in the whole document, including subsections
> etc.

Right, pinfo offers this as well; but, then you have to figure out where in
the nodes that the search has taken you and how to navigate from that node
to find additional information that you may need.  I have, in general, come
to think of info pages as a failed experiment and I know very few people
who actually prefer them over the simpler man pages.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Kee Nethery


On Nov 2, 2010, at 11:07 AM, Ian wrote:

> On 02/11/2010 14:47, jk wrote:
>> I think the key difference is that I don't want to have to *read*
>>  the
>> python docs - I want to be able to scan for what I'm looking for and
>> find it easily. That makes me productive.
>> 
> Hi jk, 
> 
> I totally agree. But you will get nowhere. 
> 
> A few weeks back I complained that 
> http://docs.python.org/reference/executionmodel.html#naming-and-binding
> was more than a little opaque - and was not understood by Python noobs such 
> as myself. 
> 
> I was invited to rewrite it and submit an improved version.  

In this world of moderated wikis one would think that noobs such as myself 
could enhance the docs when we find something confusing in the docs. 

Kee

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread John Nagle


On 11/2/2010 7:53 AM, Paul Rudin wrote:

Steven D'Aprano  writes:


A fair point -- the built-in open comes up as hit #30, whereas searching
for open in the PHP page brings up fopen as hit #1. But the PHP search
also brings up many, many hits -- ten pages worth.



OTOH googling for "python open" gives you the correct (for 2.7) page as
hit #1 - although you then have to use your browser's "find" facilty to
actually get to the description of the function in question.


   Right.  Google does a far better job of organizing Python's
documentation than the Python community does.  I don't even try
looking up anything starting at Python.org; I always start
with a Google search.  Even though Python.org's search is
powered by Google, it's inferior to a general search.

   Compare:

http://www.google.com/search?domains=www.python.org&sitesearch=www.python.org&q=open

http://www.google.com/search?q=Python+open



John Nagle
--
http://mail.python.org/mailman/listinfo/python-list

Man pages and info pages (was: Python documentation too difficult for beginners)

2010-11-02 Thread Teemu Likonen

* 2010-11-02 18:43 (UTC), Tim Harig wrote:

> The manual format contains all of the information on one page that can
> be easily searched whereas the info pages are split into sections that
> must be viewed individually. With the man pages, you can almost always
> find what you want with a quick search through the document. Info
> pages are much harder to use because you have to try and figure out
> which section the author decided to place the information that you are
> looking for.

There is also the problem that people are less familiar with info
browsers than the usual "less" pager which is used by "man" command.

With the text terminal info browser called "info" as well as Emacs' info
browser you can use command "s" (stands for "search"). It prompts for a
regexp pattern to search in the whole document, including subsections
etc.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Ian

On Nov 2, 8:47 am, jk  wrote:
> You're right in that the python docs in this case are less lines, but
> that's one of the problems. It doesn't mention anywhere the extra
> detail you've added regarding exceptions thrown. That's the kind of
> thing that probably comes through experience or some kind of
> convention which isn't obvious to beginners. Having things split into
> sections - parameters, return types, exceptions, etc - lets me find
> what I'm looking for quickly.

It doesn't mention it because those exceptions don't actually have
anything to do with the id() function.  They're just what happens any
time an unbound variable name is evaluated, in any context.  The exact
same thing could be said about any Python function in existence that
takes at least one argument.

Cheers,
Ian
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Tim Harig

On 2010-11-02, jk  wrote:
> As for the 9 paragraphs statement, there's a usability book that
> applies here - it's called "Don't make me think". I shouldn't have to

Anything that promotes a lack of thinking sends up red flags in my head.
We want to recruit smart people who think, not idiots.

> go through freeform text to find what I'm looking for when a list
> would make that information easier to find. And splitting the docs
> into sections would allow me to skip to what I'm looking for. I really
> would be much happier with your example documentation.

ctrl-f will bring up a search dialog in most graphical browsers.  '/' will
in many others.  With some practice, your fingers will be able to find
something far faster then your eyes can see it happen.

There is a religious war in the GNU community between info page as
documentation versus the traditional manual format.  The manual format
contains all of the information on one page that can be easily searched
whereas the info pages are split into sections that must be viewed
individually.  With the man pages, you can almost always find what you want
with a quick search through the document.  Info pages are much harder to
use because you have to try and figure out which section the author decided
to place the information that you are looking for.  The information may be
stored several levels deep, which means that it can be a deep productivity
hit if you don't guess the proper location on the first try.

> I think the key difference is that I don't want to have to *read* the
> python docs - I want to be able to scan for what I'm looking for and
> find it easily. That makes me productive.

The real question is what do you want to gain by your posts here.  You
should already know that most groups are, by their very nature, slow to
make changes to the status quo.  The problem tends to be exasperated in
open source projects where any changes mean that people have to donate
their time to make anything happen.  You will in general find two things to
be true:

1. Since they are dontating their time, you will find that people tend to
scratch their own iches first.

2. People who do take the time to contribute to open source projects are
people of action.  They don't tend to be appreciative of those who
constantly generate feature requests but have no inclination to do
any of the work themselves.  They do appreciate other people of
action who are interested in making the project better.

Therefore, if you truly want changes in the documentation, I suggest that,
rather then whining to the group, you make some of the changes yourself.
When you are finished, you can post a link to your alternate documentation
to this group.  If you documentation is truly better then the existing
documentation, you will not have to say another word.  People within the
community will rally around it and promote it.  If it gains wide enough
support, then there will be a movement to use it to supplant the existing
documentation.  It is the difference between whining from the sidelines and
actively participating in the game.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Ian


On 02/11/2010 14:47, jk wrote:

I think the key difference is that I don't want to have to*read*  the
python docs - I want to be able to scan for what I'm looking for and
find it easily. That makes me productive.

Hi jk,

I totally agree. But you will get nowhere.

A few weeks back I complained that
http://docs.python.org/reference/executionmodel.html#naming-and-binding
was more than a little opaque - and was not understood by Python noobs 
such as myself.


I was invited to rewrite it and submit an improved version.

Remember I said I was a noob and did not understand it. Just how can I 
rewrite it from that base?


But I'm sure that the trouble is with me. It is clear from this 
statement (rom that page)...


"If a name binding operation occurs anywhere within a code block, all 
uses of the name within the block are treated as references to the 
current block."


that, (in the given situation), name binding does not bind a name to a 
variable but to a block.



Just for the record,  I really know it is not me. English is my mother 
tongue, and I have some programming experience, in a variety of 
languages. I wrote my first program in 1964, and have been earning a 
living programming since '74. I have used Cobol, Lisp, Smalltalk, C, 
Javascript, Notes, PHP and many other languages in a commercial 
environment over the last 36 (good gracious!) years.


This lack of documentation is almost universal. You will have heard of 
the "with batteries" tag. This means that, whatever you want to do, 
there are usually many libraries available to help you do it. Every one 
will be poorly documented and most are hard to find. Yes there are 
batteries - but it is not clear which is more productive: write what is 
needed from scratch, or investigate what "batteries" are available and 
risk finding that the one you chose is missing some important feature 
down the line?


Observe though that having poor introductory documentation sells a lot 
of "How to Program in Python" type books.


Its sad really.  Python is a great little language, and deserves better. 
Without an on-ramp, noobs will struggle to get on the freeway.  And yet, 
enough will get on, that these pleas for better documentation can be 
ignored by those who know and could do something about it.


Regards

Ian

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Terry Reedy


On 11/2/2010 6:42 AM, jk wrote:


Compare for instance the differences in ease of use, and speed of use,
of these:

http://docs.python.org/library/functions.html#open
http://uk.php.net/manual/en/function.fopen.php

The former is difficult to find (try searching for 'open' in the
search box and see what you get).


duh. 'open' is a common word and if you make an unstructured search for 
it in all text, you should get a lot of hits.


The Python docs have both a Global Module Index (which I use constantly) 
and a General Index of functions (methods), classes, and terms. Learn to 
use them. If you look in the [o] section for 'open', the first entry is 
"open() (built-in function)" -- just what you were looking for. There 
are also about 30 more nicely labelled entries for 'open' in various 
modules.


> It is simply a collection of

paragraphs without strong enough contrast to differentiate the
different parts - parameters, parameter values, return types,
exceptions and related functions. It is slow to read and doesn't allow
easy visual scanning.


It is possible that this particular entry could be improved.


Is there much chance that the Python maintainers will change their
documentation system to make it more like Java or PHP?


There are plans to make doc feedback from users easier.

--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Bruno Desthuilliers


jk a écrit :

Hi,

I've been coding in PHP and Java for years, and their documentation is
concise, well structured and easy to scan.

Others have mentioned this apparently for years (see:
http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851
and http://www.russellbeattie.com/blog/python-library-docs-still-suck
and http://xahlee.org/perl-python/xlali_skami_cukta.html).


Totally unrelated, but the last example is nothing but a reference - 
xahlee is one of the worst internet troll ever.




Compare for instance the differences in ease of use, and speed of use,
of these:

http://docs.python.org/library/functions.html#open
http://uk.php.net/manual/en/function.fopen.php


Sorry but as far as I'm concerned, PHP doc sucks big time, and I find 
Javadoc-style stuff close to useless.



(snip)


Has anyone else struggled while trying to learn the language?


Not as far as I'm concerned. I found Python the easiest language to 
learn right from the beginning. Not to say the doc couldn't be improved, 
or that alternate documentations could help, but I never had any problem 
with it.



--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Paul Rudin

Steven D'Aprano  writes:

> A fair point -- the built-in open comes up as hit #30, whereas searching 
> for open in the PHP page brings up fopen as hit #1. But the PHP search 
> also brings up many, many hits -- ten pages worth.
>

OTOH googling for "python open" gives you the correct (for 2.7) page as
hit #1 - although you then have to use your browser's "find" facilty to
actually get to the description of the function in question.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

On Nov 2, 1:42 pm, Steven D'Aprano  wrote:
> It's always difficult to know how much information is too much. The PHP
> docs seem to take an "everything including the kitchen sink" approach.
> Given that approach, it makes sense to divide everything into
> subsections, one page per function. But with Python's minimalist
> approach, it would just be annoying. Compare the four lines of:
>
> http://docs.python.org/library/functions.html#id
>
> with this re-write in the PHP fashion:
>
> =
> id
> =
> (Python 1.x, Python 2.x, Python 3.x)
>
> id -- id of an object
>
> Description
> ---
>
> id(object)
>
> id returns the numeric "identity" of an object, which is guaranteed to be
> unique and constant for this object during its lifetime.
>
> Note: two objects with non-overlapping lifetimes may have the same id()
> value.
>
> Note: CPython implementation detail: This is the address of the object.
>
> Parameters
> --
>
> * object
>
>   Any object.
>
>   Note: all data in Python are objects, even ints and strings.
>
>   Note: there are no undefined objects in Python. If you call
>   id(variable) on an unbound variable name, Python will raise an
>   exception.
>
> Return values
> -
>
> Returns an integer or long integer object representing the ID of the
> argument.
>
> Errors/exceptions
> -
>
> If the argument to id() is a named variable rather than a literal, and
> that name is not bound to any object, then a NameError will be raised.
> Otherwise every call to id() must succeed.
>
> Note: if the call to id() is inside a function, the exception may be a
> subclass of NameError such as UnboundLocalError.
>
> Note: literals are not guaranteed to always refer to the same object.
>
> Changelog
> -
>
>   0.9  First version added (I think).
>
> Examples
> 
>
>    id(x)
>    id(alist[1])
>    id(instance.attribute)
>    id(module.name.attribute['key'].method(arg1, arg2).seq[2])
>
> Notes
> -
>
>    If you're still reading, I admire your persistence.
>
> See also
> 
>
>    Python's object model
>    Exceptions
>
> Steven

You're right in that the python docs in this case are less lines, but
that's one of the problems. It doesn't mention anywhere the extra
detail you've added regarding exceptions thrown. That's the kind of
thing that probably comes through experience or some kind of
convention which isn't obvious to beginners. Having things split into
sections - parameters, return types, exceptions, etc - lets me find
what I'm looking for quickly.

As for the 9 paragraphs statement, there's a usability book that
applies here - it's called "Don't make me think". I shouldn't have to
go through freeform text to find what I'm looking for when a list
would make that information easier to find. And splitting the docs
into sections would allow me to skip to what I'm looking for. I really
would be much happier with your example documentation.

I think the key difference is that I don't want to have to *read* the
python docs - I want to be able to scan for what I'm looking for and
find it easily. That makes me productive.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Grant Edwards

On 2010-11-02, brf...@gmail.com  wrote:

> A tutorial type book can also be great for reference and
> documentation (as long as its current). I would recommend a
> non-programmers tutorial to python even if you have started
> programming in other languages before. Also its a wiki book and is
> free.

To what does "it" refer in the last sentence?

> Sent wirelessly from my BlackBerry device on the Bell network.

That's nice, thank's for sharing.

-- 
Grant Edwards   grant.b.edwardsYow! Do you think the
  at   "Monkees" should get gas on
  gmail.comodd or even days?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Steven D'Aprano

On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote:

> Hi,
> 
> I've been coding in PHP and Java for years, and their documentation is
> concise, well structured and easy to scan.

Well, that's one opinion.

> Others have mentioned this apparently for years (see:
> http://stackoverflow.com/questions/4046166/easy-to-navigate-online-
python-reference-manual/4070851
> and http://www.russellbeattie.com/blog/python-library-docs-still-suck
> and http://xahlee.org/perl-python/xlali_skami_cukta.html).
> 
> Compare for instance the differences in ease of use, and speed of use,
> of these:
> 
> http://docs.python.org/library/functions.html#open
> http://uk.php.net/manual/en/function.fopen.php
> 
> The former is difficult to find (try searching for 'open' in the search
> box and see what you get).

A fair point -- the built-in open comes up as hit #30, whereas searching 
for open in the PHP page brings up fopen as hit #1. But the PHP search 
also brings up many, many hits -- ten pages worth.

But in any case, the Python search functionality could be smarter. If I 
had a complaint about the docs, that would be it. Fortunately, I have 
google :)

> It is simply a collection of paragraphs
> without strong enough contrast to differentiate the different parts -
> parameters, parameter values, return types, exceptions and related
> functions. It is slow to read and doesn't allow easy visual scanning.

It's *nine* paragraphs, three of which are one-liners, the longest of 
which is eight lines. If you have trouble reading that, well, you have a 
problem. The PHP docs for fopen are FIFTY-EIGHT paragraphs.

Okay, okay, I was unfair. I counted section headings as separate 
paragraphs. A more reasonable count is... twenty-six paragraphs, tables, 
sections and subsections. Plus *dozens* of user-contributed recipes, bug 
reports, tricks, tips and comments. And you call this concise???

Reading the docs, I'd say that PHP needs all this extra documentation 
because it's so much more complicated. fopen has all this implicit magic 
behaviour that needs documenting -- it will try to guess a scheme from 
the file name, if it can't guess the scheme it will guess that it's a 
local file, and the behaviour depends on various globals. In comparison, 
Python's open is very simple: it only opens files. No wonder Python's 
docs are simpler.

The PHP docs felt it necessary to give a warning *three times*, one after 
the other, about using binary mode when opening files. Apparently once 
was not enough.

The Description subsection of the PHP fopen doc says:

fopen() binds a named resource, specified by filename, to a stream.

What's a stream? So I read, and read, and read, and eventually, almost at 
the bottom of the official docs, I find the section "Return Values":

Returns a file pointer resource on success, or FALSE on error.

Great! Now, what's a file pointer resource, and how does it differ from a 
stream? No idea.

Contrast that with the Python docs. In the *very first sentence*, it says:

Open a file, returning an object of the file type described in
section File Objects.

with both "file" and "File Objects" being hyperlinks to the appropriate 
part of the docs. I think I'll stick with the Python style, thank you 
very much.

> The latter has clearly delineated, standardised content areas for each
> of these without excessive text. It uses tables which are easy to scan
> for possible opening modes and allows users to contribute their own
> examples.

There has been discussion on python-dev about user contributed examples. 
The pros are that users can add tricks and tips. The cons are that, 
without constant attention, the user-contributed content will grow old 
and stale, or worse, be filled with nonsense.

However, there is a Python wiki. It doesn't get anywhere near as much 
love as it deserves, and (I think) the consensus was that the official 
Python docs should stay official, but link to the wiki for user-
contributed content. This hasn't happened yet.

http://wiki.python.org/moin/

> Sadly, the use of restructured text by python doesn't allow a new
> document generator to be written - all existing documentation would need
> updating with docblocks or something similar.
> 
> Has anyone else struggled while trying to learn the language? The whole
> documentation system seems geared towards people who already know what
> they're looking for and is close to useless for beginners. I'm not the
> only one who finds google an easier way to find documentation about
> python.

Why do you think this is a bad thing? The Python docs are the reference 
manual, not a tutorial. Quite frankly, if I were a PHP developer, I'd be 
pretty annoyed at having to read this in the docs for fopen:

If you use the wrong line ending characters when writing your
files, you might find that other applications that open those 
files will "look funny".

Gosh, really? Thanks for the tip, Captain Obvious.

It's always difficult to know how

Re: Python documentation too difficult for beginners

On Nov 2, 11:49 am, Tim Golden  wrote:
> But why do you imagine that the core
> Python documentation -- developed and maintained by a group of people
> who clearly have some idea what they're doing -- should change to a
> format which happens to suit you?

It's not just me who's found the current documentation frustrating.
And sure, the developers know how to code, but they probably can't see
the project with the eyes of a beginner any more.

Making a change to how code is documented to allow more javadoc-style
documentation to be produced could help people migrate from a java
background and ease the learning curve for them, leading to wider
adoption of the language. It wouldn't necessarily mean that the
current documentation style would need to change either.

> In short, please feel free to contribute directly to the core
> documentation effort, or to produce alternatives yourself

I may well do that.

@Tim Wintle
> Personally I use Google, e.g.
> "list site:docs.python.org"
> to bring up documentation about the list type.

Surely you shouldn't have to go to google though? Or the interpreter?
Maybe it's just what you're used to, but I'd expect the language's web
site to provide enough of a reference in itself, while using google
for examples.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Antoine Pitrou

On Tue, 2 Nov 2010 04:23:49 -0700 (PDT)
jk  wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
> 
> Why aren't the official docs like this, and why has it taken me 2 days
> of searching?

What's wrong with this:
http://docs.python.org/library/
?

If you have specific ideas for improvements, you can open issues at
http://bugs.python.org.

Thank you

Antoine.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Tim Wintle

On Tue, 2010-11-02 at 04:23 -0700, jk wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
Aaaarrr

> Why aren't the official docs like this,
Because not everyone likes documentation like that. Personally I far
prefer the existing documentation to the JavaDoc-style link you sent.

> and why has it taken me 2 days of searching? 
> All this needs is a search engine behind it and it'd be
> perfect.

Personally I use Google, e.g.

"list site:docs.python.org"

to bring up documentation about the list type.





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread brf256

A tutorial type book can also be great for reference and documentation (as long 
as its current). I would recommend a non-programmers tutorial to python even if 
you have started programming in other languages before. Also its a wiki book 
and is free. 

-Braden Faulkner
Sent wirelessly from my BlackBerry device on the Bell network.
Envoyé sans fil par mon terminal mobile BlackBerry sur le réseau de Bell.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Martin P. Hellwig


On 11/02/10 10:42, jk wrote:


Is there much chance that the Python maintainers will change their
documentation system to make it more like Java or PHP? How would I go
about trying to make that happen?
I am by no means an authority however since you ask it here I feel 
compelled to give you my opinion :-)


In general I would think that more documentation is always welcome, if 
you feel like you can make a contribution, excellent, please do!


However, I found that the documentation available was enough for me, and 
I didn't even have to go to the googles for that.


Typing help(thing_i_want_info_of) in the interpreter gives me precise 
consistent information for what I need to do with whatever it is I am 
doing and yes that is largely a replication of what is mentioned on the 
site itself (well more the other way around actually).


In the odd cases this doesn't help me, I google for examples.
If that doesn't help I look at the modules __file__ and open that module 
to read the source.


And when I started 10 odd years ago with Python it was my first language 
with no prior confusion of other languages, since then I extended my 
knowledge with C and assembler but on a day to day basis I still use Python.


--
mph

--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread Tim Golden


On 02/11/2010 11:23, jk wrote:

This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
about.

Why aren't the official docs like this, and why has it taken me 2 days
of searching? All this needs is a search engine behind it and it'd be
perfect.


I'm glad you find the epydoc format useful. And I'm glad that various
people have taken the trouble to produce documentation for Python in
various formats that suit them. But why do you imagine that the core
Python documentation -- developed and maintained by a group of people
who clearly have some idea what they're doing -- should change to a
format which happens to suit you?

The Python documentation source and the source code of Python itself
are all freely available. Any initiative by you or by others to
produce alternative, possibly searchable and commentable, versions of
them would I'm sure be welcomed by many. But not everyone finds, eg,
the PHP style of user annotation helpful. Not everyone likes epydoc
output: I don't myself.

In short, please feel free to contribute directly to the core
documentation effort, or to produce alternatives yourself and to
advertise them here or elsewhere within the Python community. But
please don't come along and say "Why aren't the Python docs like
 which happens to suit me better?"

TJG
--
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
about.

Why aren't the official docs like this, and why has it taken me 2 days
of searching? All this needs is a search engine behind it and it'd be
perfect.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python documentation too difficult for beginners

2010-11-02 Thread srinivas hn

If you are really beginner in python you can look into the dive into
python,search as in google as the same its quite helpful for beginners.Also
you can go for the byte of python.

CHEERS
CNA
9986229891


On Tue, Nov 2, 2010 at 4:42 PM, jk  wrote:

> Hi,
>
> I've been coding in PHP and Java for years, and their documentation is
> concise, well structured and easy to scan.
>
> Others have mentioned this apparently for years (see:
>
> http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851
> and http://www.russellbeattie.com/blog/python-library-docs-still-suck
> and http://xahlee.org/perl-python/xlali_skami_cukta.html).
>
> Compare for instance the differences in ease of use, and speed of use,
> of these:
>
> http://docs.python.org/library/functions.html#open
> http://uk.php.net/manual/en/function.fopen.php
>
> The former is difficult to find (try searching for 'open' in the
> search box and see what you get). It is simply a collection of
> paragraphs without strong enough contrast to differentiate the
> different parts - parameters, parameter values, return types,
> exceptions and related functions. It is slow to read and doesn't allow
> easy visual scanning.
>
> The latter has clearly delineated, standardised content areas for each
> of these without excessive text. It uses tables which are easy to scan
> for possible opening modes and allows users to contribute their own
> examples.
>
> Sadly, the use of restructured text by python doesn't allow a new
> document generator to be written - all existing documentation would
> need updating with docblocks or something similar.
>
> Has anyone else struggled while trying to learn the language? The
> whole documentation system seems geared towards people who already
> know what they're looking for and is close to useless for beginners.
> I'm not the only one who finds google an easier way to find
> documentation about python.
>
> Is there much chance that the Python maintainers will change their
> documentation system to make it more like Java or PHP? How would I go
> about trying to make that happen?
> --
> http://mail.python.org/mailman/listinfo/python-list
>
-- 
http://mail.python.org/mailman/listinfo/python-list

Python documentation too difficult for beginners