Kapeli

Instructions on how to generate docsets and docset feeds are found below. There is no method that is best for every case, so you’ll have to consider all and decide which is the best for you.

If you can’t get it to work, email me and let me know exactly what you’ve done so far and what error you’re getting. If you’re generating a docset that could be of use for other developers as well, email me and I might include it with Dash.

Creating docsets for your Objective-C project (from source files)

If you’re dealing with Objective-C source files, you can use AppleDoc to create docsets that are very similar to ones generated by Apple. For instructions, check out the AppleDoc website. The Cocos2D docset included with Dash has been generated using AppleDoc.

Creating Docsets for Python/Sphinx-Generated Documentation

See https://github.com/gpambrozio/PythonScripts#PythonDocs2DocSet.

Creating docsets for JavaDoc-Generated Documentation

Creating Docsets using Doxygen (from source files)

As specified on the Doxygen website, Doxygen works with C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D. I have never used Doxygen so I can’t really write a tutorial on it, but I have tested Dash with Doxygen generated docsets and everything works. As far as I can tell, the best information on Doxygen docsets can be found on the Apple website. If you know of a better tutorial, let me know.

Creating Docsets using docsetutil (for any existing documentation)

For all the information on generating docsets and indexing them using docsetutil, see this page.

As far as I know, you need to do this:

• Create this folder structure: Example.docset/Contents/Resources/Documents/
• Place the documentation you already have in the Example.docset/Contents/Resources/Documents/ folder (in a separate folder)
• Download and edit this sample Info.plist and place it in the Example.docset/Contents folder.
• Place a Nodes.xml file in the Example.docset/Contents/Resources folder. This is just a XML file that points to the main index file of your documnetation. See Nodes.xml for an example.
• And now the hard part. You need to create a script (or application or whatever) that will go through your documentation and index it. The goal is to generate a Tokens.xml file which contains information about where different things are. Here is process.sh, which was used to generate the Tokens.xml file for the Android documentation. As far as I can tell, you need to create entires in the form of:

• <File path="relative/path/to/file">
    <Token><TokenIdentifier>//apple_ref/language/type/name</TokenIdentifier></Token>
    </File>

• Language is the programming language of the entry. If you’re getting errors, it means docsetutil doesn’t recognise it. Set it to “cpp”, for example, it won’t make a difference as far as Dash is concerned.
• Type is the type of the entry (e.g. “cl” for class). For a list of possible values that Dash recognises, see the list at the bottom of this page.
• Name is the name of the entry (i.e. the name of the class).
• So basically you have to parse the documentation files and extract names, types and paths to the stuff you want indexed.
•  Final step: install Xcode Tools if you haven’t already and run:
• /Developer/usr/bin/docsetutil index <Docset.docset>

Creating Docsets using SQLite (for any existing documentation)

Docsets are esentially just a folder containing the documentation and a SQLite database that indexes the files. Dash supports special docsets with a really simple SQLite index. If you like SQL, you might prefer this method.

• First of all, we need to set up the docset folder structure:
• Create this folder structure: Example.docset/Contents/Resources/Documents/
• Place the documentation you already have in the Example.docset/Contents/Resources/Documents/ folder (in a separate folder preferably)
• Download and edit this sample Info.plist and place it in the Example.docset/Contents folder
• Create a SQLite database in the file: Example.docset/Contents/Resources/docSet.dsidx with the following query:

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

• You need to create a script (or application or whatever) that will index your documentation and add appropriate rows into the SQLite database. The database values are:
• id is just the primary key, auto-increment it.
• name is the name of the entry. For example, if you are adding a class, it would be the name of the class. This is the column that Dash searches.
• type is the type of the entry. For example, if you are adding a class, it would be “cl”. For a list of types that Dash recognises, see the list at the bottom of this page.
• path is the relative path towards the documentation file you want Dash to display for this result. It can contain an anchor (#).
• To see an example database that is filled with values, open ~/Library/Application Support/Dash/DocSets/jQuery.docset/Contents/Resources/docSet.dsidx in your SQLite manager.

Possible entry types

• Class -> cl
• Category -> cat
• Protocol -> intf
• Binding -> binding
• Method -> clm
• Property -> instp
• Type Definition -> tdef
• Function -> func
• Macro -> macro
• Constant -> clconst

Host your own Dash documentation feed

Important: Dash does not support Xcode documentation feeds.

Dash documentation feeds are very simple, check one out at http://kapeli.com/feeds/Java.xml.

It’s a XML file that contains the following:

• A root <entry> element
• A <version> element. You can use any versioning system you want. Dash will use string comparison to determine whether or not to download an update.
• One or several <url> elements. These point to the URL of the archived docset.

To archive your docset, run the following command:

• tar --exclude='.DS_Store' -cvzf Java.tgz Java.docset

Currently only one docset per feed is supported (only one <entry>).