Python’s documentation at your fingertips

Email This Post Email This Post

The pain

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:

  • 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 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, 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 Dash with this docset makes your lives easier. It has certainly made mine. If you have any comments about this docset leave a comment below.

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.

What causes yeast infections before periods what causes yeast infections before periods. Laser armpit sweating treatment cost laser armpit sweating treatment cost. Phentermine 37.5 drug screen phentermine 37.5 drug screen. Exercises to reduce gerd exercises to reduce gerd. Hcg weight loss supplement hcg weight loss supplement. Dating site italian men dating site italian men. Low price teramine low price teramine. How to get rid of herpes on lips how to get rid of herpes on lips. Many mg hoodia effective many mg hoodia effective. Learn to master piano learn to master piano. Acyclovir cream treatment herpes simplex labialis acyclovir cream treatment herpes simplex labialis. Home remedies for sweat bumps home remedies for sweat bumps. Jamaican herbs for fibroids jamaican herbs for fibroids. Male treatment for bv male treatment for bv. Does pcos cause insulin resistance does pcos cause insulin resistance. Obytrim dosage obytrim dosage. L-arginine hgh dosage l-arginine hgh dosage. Pcos diet pills pcos diet pills. Acid reflux left untreated acid reflux left untreated. Piano lessons hornsby nsw piano lessons hornsby nsw. Best protein shakes weight loss best protein shakes weight loss. Superior canal dehiscence syndrome treatment superior canal dehiscence syndrome treatment. Gyno cures gyno cures. Tmj subluxation treatment tmj subluxation treatment. Dating websites best dating websites best. Acai berry diet explained acai berry diet explained. Ovarian cyst symptoms pain ovarian cyst symptoms pain. Cocks cam cocks cam. Removing psoriasis marks removing psoriasis marks. Companies with retirement plans companies with retirement plans. Buy hoodia online buy hoodia online. Hoodia coupon hoodia coupon. Tinnitus retraining therapy sacramento tinnitus retraining therapy sacramento. Boots hair loss products boots hair loss products


Keep tuned for more technical and non technical posts. You can subscribe by email, RSS or following me on twitter.


Email This Post Email This Post
  • guest

    I usually use IPython for documentation. Type “import os”. Then os. lists everything you can call or do with it. Type “os?” prints the module’s docstring. Type “os.kill?” prints out the function with it’s signature and args and docstring. Type “edit -x os”, and it will open the python module in your favorite editor.

    • http://blog.codecropper.com/ Gustavo Ambrozio

      I have not heard about IPython before. I’ll have a look. Thanks for the tip.

  • http://www.ekosdeux.com/ PetroEkos

    Awesome! Thanks for sharing. I never thought of using Dash for something else. 

  • http://twitter.com/AnthonyNystrom Anthony Nystrom

    Really nice! Thank you.

  • Sean Lynch

    Would it be difficult to modify your import script to build a docset for Google’s App Engine python sdk (http://code.google.com/appengine/docs/python/)?  I spend a great deal of time there, but after finding dash, I would love to use it instead of a browser.

    • http://blog.codecropper.com/ Gustavo Ambrozio

      If the documentation were generated by sphinx as Python’s docs are it would be easier… It won’t be easy but it’s not rocket science either. Take a look inside the script and give it a go.

      • techniq

        Thanks, I’ll take a look.

  • http://j2labs.net j2d2

    I like to use this simple technique: http://j2labs.tumblr.com/post/822342102/pyman

    • http://twitter.com/gpambrozio Gustavo

      This is cool, but give Dash a try. You won’t regret it.

  • https://launchpad.net/~markgrandi mark grandi

    I thought i commented but i guess it got lost, i forked your repo on github and rewrote…a lot of it to make it work with the as3 documentation =) thanks again for turning me onto this program, it really is awesome! I probably will modify your original script a bit to make it more pythonic and use some of the built in methods (like os.path.join, with statements, etc) that i noticed, but it was good overall for a first python attempt :)

    • http://twitter.com/gpambrozio Gustavo

      Thanks mark. I’d appreciate it if you do a pull request once you’re done. Love to see what someone with more python experience will do to it.

  • Too

    Thanks for the sharing, will have a try Dash definite.

  • Acidrain_

    Damn this looks so cool.
    Is there something similar for Windows or Linux ?

  • harijay

    I heard about dash on the Django Round Up podcast and immediately purchased a copy…thanks for the python docsets..I can’t wait to see if there are docsets for other libraries in the django/python space