How to Build Dash Docsets

Posted on In ,

Dash is a popular API browser on macOS. Alternatives on Windows include Zeal and Velocity.

This guide follows the official Dash documentation. Let me know if you spot any mistakes.

Convert from other formats

Dash docsets can be converted from several standard documentation formats.

Sphinx and PyDoctor projects (such as Python docs) can be converted with doc2dash. You will also need sphinx. Install both with pip.

Because the straight conversion path is well documented, I will not repeat it here.

Extract from HTML

Some projects only ship raw HTML—for example, the local PyQt4 docs I needed. HTML lacks a common structure, so you have to script the conversion yourself.

The official steps:

Create the docset folder

On macOS:

mkdir -p <docset name>.docset/Contents/Resources/Documents/

On Windows create the same folder tree manually, and remember the root must end with .docset.

Place the HTML files

Copy the HTML docs into <docset name>.docset/Contents/Resources/Documents/.

Dash essentially renders HTML inside the right-hand pane, so it needs direct access to the files. To make search work, we must also build an index.

Add Info.plist

Download Info.plist and tweak the fields as needed. Drop it into <docset name>.docset/Contents/.

Create the SQLite index

Dash stores the index in SQLite. Inside <docset name>.docset/Contents/Resources/, create docSet.dsidx with the following schema:

CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);

Populate the index

Now insert entries into the database. Each row needs a name, type, and path. Suppose you want the PyQt4 method QLineEdit.isReadOnly() to be searchable:

  • name: isReadOnly
  • type: Method
  • path: qlineedit.html#isReadOnly

name is what appears in the search results. type controls the icon in Dash—pick from the supported entry types. path is the relative URL inside your HTML docs.

Write a script that extracts these values and insert them:

INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES ('name', 'type', 'path');

My own converter for the PyQt4 HTML docs lives here: chroming/html2docset.