Python's documentation at your fingertips

Author: by Gustavo Ambrozio

[In this reprinted #altdevblogaday in-depth piece, Arrived's senior software engineer Gustavo Ambrozio shares the useful tool he created for searching Python documentation with Dash.] As I mentioned in my last blog post, I started learning Python some time ago and fell in love with it. But, as with any new programming language, I spent a lot of time browsing through the documentation to find out the correct name of the method to find a substring within a string for example. Is it indexOf, find, rangeOfString, locate??? Off I went to the (very well done, btw) online Python docs to look for the right method in the string module. In the meantime, I also fell in love with another tool: Dash. If you're an iOS developer and don't have Dash, you should go get it right now! It's one of the most useful tools in my tool belt at the moment. And for the very lowprice of free you just can't go wrong. As I said to the author, I'd gladly pay good money for it. Dash's first use for me was to browse inside iOS' documentation. I never liked XCode Organizer's documentation browser. The search is incredibly slow, pages take forever to load, there's no easy way to jump to a method's documentation, you name it… Dash is the complete opposite:

Not to mention other very nice features, such as a collector of code snippets and as a text auto expansion tool. Even if you're not an iOS or OSX developer, Dash can be a great tool just to collect snippets and auto expand text. Enough praise, let's go back to the problem. Dash can be used to browse through any documentation that has been bundled in Apple's docset format. When I learned this, one of those flashbulbs appeared over my head and I immediately started to scour the web for a version of Python's documentation in docset format only to find that such a thing either does not exist or is very well hidden. Using the snake to help the snake So I decided to take matters into my own hands and build this documentation myself. Using Python, of course. With the help of Dash's author, I learned how to build docsets that were easily searchable inside Dash. After a few hours of coding, reading Apple's documentation, and building regexes to collect all the information I thought should be in the documentation, I managed to create a docset, configure Dash to use it and, voila, instant Python documentation search! I managed to generate documentation for Python 2.7.2 and for 3.2.2, the latest versions at this time. Click the links to download and feel free to use them. You'll have to unzip the file and put the resulting .docset bundle somewhere. I would recommend putting them in ~/Library/Developer/Shared/Documentation/DocSets as this is the place XCode will look for when searching for docsets. I believe Dash will look in this folder too or at least is the default folder for when you try to add new docsets to it. And I'm proud to say that Dash's author will bundle this bundle (the 2.7.2 version) with Dash's new version. If you want to have documentation for version 3.2.2 you can download my version and use that instead. Oh, and before I forget, Dash now comes with a lot of docsets created by the author. Currently Android, Java, Perl, Python, PHP, Ruby, jQuery and Cocos2D docsets are included. Plus, I'm adding this script to my PythonScripts github repository. Feel free to grab it, fork it, use it and improve it. I love getting pull requests with improvements on my repos. To use the script, you'll need to have the BeautifulSoup module installed (sudo pip install beautifulsoup4). I use it to parse the documentation's HTML so I can find all interesting methods, functions, and classes to grab. I also had to add anchor tags to all HTML files so Dash could jump to the correct place inside the HTML. This is what you have to do to generate a new version of the documentation from the HTML version:

Conclusion This is my first contribution to the Python community. I hope you like it and that using Dash with this docset makes your lives easier. It has certainly made mine. If you have any comments about this docset, please leave a comment in my blog's post. The docset does not have the complete documentation (it does not have the tutorials and howto for example), as I personally use it only as a reference. But, as I said before, feel free to change the script to include more stuff and make a pull request so I can add it to my repo. [This piece was reprinted from #AltDevBlogADay, a shared blog initiative started by @mike_acton devoted to giving game developers of all disciplines a place to motivate each other to write regularly about their personal game development passions.]