Importing Python Docs into Dash

Mar 12 2014

Dash is a cool little multi-language API documentation manager for OS X. While it's free (as in beer) with some limits, it is one of the few programs I don't mind paying for.

Dash makes it easy to install the core library references for a variety of languages and tools. Mine, for example, has Go, Python, Java, MySQL, PostgreSQL and a few other libraries all installed. But Dash doesn't include documentation for libraries.

I've been writing a lot of Python in the last few weeks, and I use several libraries frequently. Importing those docs into dash makes my life much easier. Here's how I added the Boto docs to Dash.

(I also repeated the exact same process with Psycopg2, the Python PostgreSQL driver, and the same process should hold for just about any Python package documented with Sphinx.)

Installing doc2dash and sphinx

There's a great little tool for converting Python HTML documentation to Dash's format: doc2dash. It takes the output of Sphinx documentation and converts it to a Dash documentation package.

To do this, we'll use both Sphinx and doc2dash. I installed them the usual way:

$ pip install doc2dash
$ pip install sphinx

Next, I need the source for the documentation I am going to build.

Generate the Boto Docs

Now we are ready to generate the HTML documentation from the Boto source. The first step for us is to grab the source.

$ git clone git@github.com:boto/boto.git
$ cd boto/docs

At the time of this writing, there is one configuration parameter missing from the Boto docs that will prevent it from working with doc2dash. Edit the boto/docs/source/conf.py file and add the following line somewhere near the end of the file:

html_use_index = True

This causes the generator to create a genindex.html file that doc2dash uses.

Now we can run sphinx-build to generate the documentation:

$ mkdir html
$ sphinx-build source html

The above will take several minutes, but by the end, your html/ directory should be loaded with docs.

Running doc2dash

Once Sphinx is done compiling the documentation in HTML form, we can begin the process of importing it into Dash.

$ doc2dash -A html --name Boto

The above will read the contents from the html/ directory and create a doc set, importing it into Dash with the name Boto.



comments powered by Disqus