![\"\"](\"http:\/\/www.bin-co.com\/blog\/wp-content\/uploads\/2008\/03\/python-logo.gif\" "\\"Python"){kind=logo}
<\/p>\n<\/p>\n
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<\/a>) – 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<\/strong>.<\/p>\n By Python Manual, I mean the official Python Manual available at http:\/\/docs.python.org\/<\/a>. I have downloaded the entire manual to my system as HTML files<\/a> and use that as a reference<\/strong> when working with Python. This is what I have done for all the other languages I work with…<\/p>\n 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<\/strong>. When I need to find a function, all I have to do is search through this page<\/strong>. These pages in the documentation serves this purpose…<\/p>\n What about Python? Well, Python don’t have such a page<\/strong> in their manual. The nearest one I could find a combination of four pages – Module Index<\/a> + Library Index<\/a> + Tutorial Index<\/a> + Language Index<\/a>. Its no where near as useful.<\/p>\n 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<\/strong> capabilities. Don’t believe me? OK – go to Python Docs<\/a> and try to find the documentation for the function that, say, reverses an array. Now go to the PHP site<\/a> and do the same.<\/p>\n 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<\/strong> in their downloads section<\/a>. CHM solves the problem as you can search through them easily.<\/p>\n PHP, on other hand, provides the CHM file<\/a>. This makes the PHP manual much more easier to use.<\/p>\n Even though Python don’t officially provide a CHM file, others have made it available on the net. Its just a google search away<\/a>. But I prefer to get these stuff from an official source.<\/p>\n The worst sin of the Python manual is that the documentation is not detailed enough<\/strong>. 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<\/a>…<\/p>\n 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…<\/p>\n 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.<\/p>\n\n
Finding a Function<\/h2>\n
\n
Reference Formats<\/h2>\n
Level of Detail in the Documentation<\/h2>\n
\n
x = [1,2,4]\nx.reverse()\n#Now x has the value [4,2,1]<\/code><\/pre>\n