Unlike the other scripting languages I work with(like PHP, Ruby, JavaScript, etc.), I am not comfortable using Python. I have made some stuff in Python(for example, frees) – but I could get into the flow as easily as with other languages. For the longest time, I thought it was because of the whitespace issue. But recently, I created a small Python script – that’s when I understood that whitespace does not concern me. What make me angry at python is its documentation/manual.
By Python Manual, I mean the official Python Manual available at http://docs.python.org/. I have downloaded the entire manual to my system as HTML files and use that as a reference when working with Python. This is what I have done for all the other languages I work with…
- Perl
- PHP
- Ruby
- JavaScript
- CSS
- etc.
Finding a Function
There is one big problem with using HTML files as your reference – you cannot search through it. So I try to find a page in the documentation that lists all the functions in a single page. When I need to find a function, all I have to do is search through this page. These pages in the documentation serves this purpose…
What about Python? Well, Python don’t have such a page in their manual. The nearest one I could find a combination of four pages – Module Index + Library Index + Tutorial Index + Language Index. Its no where near as useful.
Even if you are online(remember, many people are not connected all the time), its still not easy to find a function in Python documentation – even with searching capabilities. Don’t believe me? OK – go to Python Docs and try to find the documentation for the function that, say, reverses an array. Now go to the PHP site and do the same.
Reference Formats
Anyway, I cannot really complain about the the availability of the ‘function page’. Its just the way I prefer – other people may not want such a page. But I can complain about the fact that they don’t provide a CHM file in their downloads section. CHM solves the problem as you can search through them easily.
PHP, on other hand, provides the CHM file. This makes the PHP manual much more easier to use.
Even though Python don’t officially provide a CHM file, others have made it available on the net. Its just a google search away. But I prefer to get these stuff from an official source.
Level of Detail in the Documentation
The worst sin of the Python manual is that the documentation is not detailed enough. To better understand this, let’s take an example – say the array reversal function. First we take a look at the Python documentation for this function…
- reverse()
- Reverse the order of the items in the array.
One line. That’s it! If you are not well versed in Python, you will have no idea of how to use this function – because there is no example. Most people will expect that the array must be given as the argument. But the argument list is empty in the documentation. That’s because the array is not passed as an argument – rather, in Python, this function is a member function of the array object – so the proper usage will be something like this…
x = [1,2,4]
x.reverse()
#Now x has the value [4,2,1]I know that because I know Python – but if a new user manages to find the documentation for this function, he will be confused. Another thing – I am not saying that there are no examples in the documentation – examples are given for a lot of functions. But its no where near the level that PHP has achieved.
OK – now lets see the PHP manual for the same function – array_reverse(). There is an entire page for that function. Not just for this function – there is one page of documentation for every function in PHP. And there are examples. And at the end, there is a collection of ‘user notes’ – making each function much clearer. Beautiful!
I feel a bit guilty about comparing Python with PHP documentation – PHP has the best documentation in its class of languages. But still, Python has a lot to learn from PHP(I wanted to say that for a long time đŸ˜‰ ).
I must admit that, in many ways does the PHP documentation much better than the python one.
On the other hand have a look at the equivalent java documentation
http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collections.html#reverse(java.util.List)
not much better then they python version.
That should not be an excuse to have bad documentation, I totally agree that the python docs don’t have enough examples. But in one thing you are not quite right. The chm file of the python documentation is included in your python installation, so no need to download (although it should definitely be available online).
@Mauli
The CHM file is included with the Python installation? I did not know that. Anyway I don’t think its available in Linux – CHM files are not supported on Linux. But I prefer using CHM even though I am on Linux.
Python does not have a big user base as PHP.
That is why the documentation is still in the early stages of development.
Contribute!!!
That’s because the runtime documentation is so much better than most people don’t spend much time on the site.
>>> x = [1,2,4]
>>> print x.reverse.__doc__
L.reverse() — reverse *IN PLACE*
>>> dir(x)
[‘__add__’, ‘__class__’, ‘__contains__’, ‘__delattr__’, ‘__delitem__’, ‘__delslice__’, ‘__doc__’, ‘__eq__’, ‘__ge__’, ‘__getattribute__’, ‘__getitem__’, ‘__getslice__’, ‘__gt__’, ‘__hash__’, ‘__iadd__’, ‘__imul__’, ‘__init__’, ‘__iter__’, ‘__le__’, ‘__len__’, ‘__lt__’, ‘__mul__’, ‘__ne__’, ‘__new__’, ‘__reduce__’, ‘__reduce_ex__’, ‘__repr__’, ‘__reversed__’, ‘__rmul__’, ‘__setattr__’, ‘__setitem__’, ‘__setslice__’, ‘__str__’, ‘append’, ‘count’, ‘extend’, ‘index’, ‘insert’, ‘pop’, ‘remove’, ‘reverse’, ‘sort’]
Official chm download: http://www.python.org/ftp/python/2.5.2/Python25.chm
I think you should learn to use the Python interactive shell instead to complain for the absence of examples in the documentation.
Granted, there is always room for improvements… but some people (not me) are working at it.
Just taking your “finding a function” example: have a look at http://docs.python.org/dev/genindex.html
I think you might be pleasantly surprised…
I’ve had the same complaint for a while..
After a long debate with a co-worker we decided it was a virtuous circle problem. Which the PHP community set up a base standard for documentation and then continued to improve upon it. The python community set their base and while it might have improved, it designed for a _very_ different group of users.
Think of it this way:
* PHP is the current incarnation of Basic — so the documentation is targeted at that class of users
* Python is C so targeted at that class of users (aka, read the code luke)
Fundamentally, I want documentation that is more akin to PHP (or java) — Verbose, clear parameter and clear returns. Heck, the best part of the PHP and MySQL documentation is the user comments, where real code examples exist around the problems.
>> I think you should learn to use the Python interactive shell instead to complain for the absence of examples in the documentation.
Unfair. I also prefer to read good documentation and on principle prefer more examples in the documentation without having to guess behavior from interactive experimentation.
As the editor of the quick reference card in the original O’Reilly Python book, I have to say the documentation hasn’t changed all that much in the 10+ years since the 1.0 Python release. Personally I think it’s actually fairly good — as someone says, it’s ratheer comparable to Sun’s Java API documentation — but it’s a little surprising how much the documentation would look familiar to a user of release 0.9!
It would be interesting to set up a wiki based on the documentation, see what changes users come up with, and use that as a clue as to what documentation in the official docs could use more work.
gotapi.com ftw
Your example of reverse is trivial for by definition it takes no arguments. All functions in the python documentation contain the arguments and keyword arguments in the definition. Moreover, how much more information than “reverses the items in a list” do you need?
As for not being able to search the documentation, have you every heard of:
(1) Google?
(2) grep? (from the shell)
(3) dir or __doc__ ? (from within the interpreter)
Your article can be basically summarized as ‘I don’t understand how to use python therefore it is flawed’. My honest opinion: I’d rather you didn’t write python because I may have to one day read the code that you write.
@André Roberge
Thanks for the link. The search needlessly uses ajax – but still, its much better than the default search.
@Others
Yes, I know about the interactive shell. I use that a lot when I am working on Python. But I don’t expect beginners to know about it. They need reference manuals. And what about Python developers on Windows? I think they are allergic to the terminal window đŸ˜‰
@Marc
> (2) grep? (from the shell)
I am not sure what you mean – how do you find the python documentation of a given function using grep? Which folder should I search?
> Mike at June 7th, 2008 at 12:25 am
>
> That’s because the runtime documentation is so much better than most people don’t spend much time on the site.
Sorry, I love Python a great deal more than PHP, but the shell docs are garbage. Your example assumes the user knows how to create a list and that a list has a reverse function. What the poster is talking about is for complete novices who like to discover functionality by using *search* terms. I have to agree with him that simply going to the PHP site or CFM and entering “reverse array” and getting the function you’re looking for is a lot easier than somehow magically knowing about Python lists and the list’s attributes.
As a new python user, I must say that I find the documentationv is verging on prohibitive. What I tend to do is output the pydoc documentation for a module to a text file and work from that. Not exactly ideal as you have to know what module you’re looking for before you can do it, but my main problem with python’s online documentation is the lack of function descriptors and examples.
I still find it way more fun than PHP and I can’t wait until I’m as familiar with it as I am PHP
The CHM is on the Python website: http://www.python.org/download/releases/2.5.2/
Reading chm files on linux requires you to install additional packages which you can choose from ‘xchm’ or ‘gnochm’.
I do agree, we would need examples in the documentation to add more value. It may be trivial to google in some cases but a real pain for some libraries which we use occasionally.