Python documentation

[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 going through the documentation to find the correct method name to find a substring in a string for example.

Is it indexOf, find, rangeOfString, locate ??? I went to the online Python documentation (very well done, by the way) to find the correct method in the string module.

In the meantime, I also fell in love with another tool: Hyphen. If you are an iOS developer and don’t have Dash, you should download it now! This is one of the most useful tools in my tool belt right now. And for the very low price of free You can not be wrong. As I told the author, I would gladly pay dearly for it.

The first use of Dash for me was browsing the iOS documentation. I never liked XCode Organizer’s documentation browser. The search is incredibly slow, the pages take forever to load, there is no easy way to access the documentation for a method, name it …

Dash is quite the opposite:

• The search is incredibly fast;
• Once you find the class you are looking for, it creates a list of all the methods so that you can access them quickly;
• If you click on the declaration of a method, it automatically copies it to your clipboard. Now it’s a snap to create delegate methods;
• You can search the documentation for a class just as easily;

Not to mention some other great features, such as a snippet collector and an automatic text expansion tool. Even if you are not an iOS or OSX developer, Dash can be a great tool just for collecting snippets and developing text automatically. Enough praise, back to the problem.

Dash can be used to browse any documentation that has been gathered in Apple’s docset format. When I learned about this, one of those flash bulbs popped over my head and I immediately started scouring the web looking for a version of the Python documentation in docset format to find that one such thing does not exist or is very well hidden.

Use 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 the author of Dash, I learned how to build docsets which were easily searchable in Dash. After a few hours of coding, reading Apple’s docs, and creating regular expressions to collect all the info I thought should be in the docs, I managed to create a docset, configure Dash for the use and, voila, an instant search for Python documentation!

I managed to generate some documentation for Python 2.7.2 and for 3.2.2, the latest versions at the moment. Click on the links to download and feel free to use them.

You will need to unzip the file and place 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 think Dash will also look in this folder or at least is the default folder when trying to add new docsets to it.

And I’m proud to say that the author of Dash will bundle this bundle (version 2.7.2) with the new version of Dash. If you want to have documentation for version 3.2.2, you can download my version and use it instead. Oh, and before I forget, Dash now ships with a lot of author-created docsets. Currently, Android, Java, Perl, Python, PHP, Ruby, jQuery, and Cocos2D document sets are included.

In addition, I add this script to my PythonScripts github repository. Don’t hesitate to grab it, fork it, use it and improve it. I like to receive draw requests with improvements on my deposits.

To use the script you will need the Beautiful Soup module installed (sudo pip install beautifulsoup4). I use it to parse the HTML code of the documentation to find all the interesting methods, functions and classes to grab. I also had to add anchor tags to all HTML files so Dash could jump to the right place in the HTML code.

Here is what you need to do to generate a new version of the documentation from the HTML version:

1. Download the documentation for the desired version here. You need to download the zip file for the HTML version of the documents.
2. Expand the documentation somewhere.
3. Open Terminal and navigate to the folder where you expanded the documents.
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 into a folder. Again, I recommend ~ / Library / Developer / Shared / Documentation / DocSets
7. Use it!

Conclusion

This is my first contribution to the Python community. Hope you like it and that using Hyphen with this docset simplifies your life. He certainly did mine. If you have any comments on this docset, please leave a comment in my blog post.

The docset doesn’t have the full documentation (it doesn’t have the tutorials and howto for example), as I only use it personally as a reference. But, like I said before, feel free to edit the script to include more stuff and make a pull request so I can add it to my repository.

[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.]