Importing Python Docs into Dash
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.
