The pain

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:

  • The search is amazingly fast;
  • Once you find the class you’re looking for it builds a list of all the methods so you can quickly jump there;
  • If you click on a method’s declaration it automatically copies it to your clipboard. It’s now a breeze to create delegate methods;
  • You can search inside a class documentation just as easily;

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, voilá, instant Python documentation search!

I managed to generate documentation for Python 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 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, 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:

  1. Download the documentation for the version you want here. You should download the zip file for the HTML version of the docs.
  2. Expand the documentation somewhere.
  3. Open terminal and cd to the folder where you expanded the docs.
  4. Run the script from this folder.
  5. The script will create a python.docset bundle with all the necessary files.
  6. Move the python.docset bundle to some folder. Again, I recommend ~/Library/Developer/Shared/Documentation/DocSets
  7. Use it!

Conclusion

This is my first contribution to the Python community. I hope you like it and that using 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.