Kapeli

Generating Dash Docsets

Instructions on how to generate docsets and docset feeds (for Dash) 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.

Generate a docset from:

1. Objective-C Source Files

AppleDoc can be used to generate docsets from Objective-C source files. Please note that if you are trying to generate a docset for an Objective-C framework, it's very likely that a docset for that framework is already available at CocoaDocs.org.

Here's an example of how to use AppleDoc:

appledoc --project-name "Cocos2D" --project-company "Kapeli" --company-id com.kapeli --ignore ".m" --explicit-crossref --keep-undocumented-objects --keep-undocumented-members --no-repeat-first-par --no-warn-missing-arg --no-warn-undocumented-object --no-warn-undocumented-member --no-warn-empty-description --docset-bundle-id "cocos2d" --docset-bundle-name "Cocos2D" --keep-intermediate-files --output ~/Desktop/Cocos2D .
When you're done generating your docset, scroll down to the bottom of this page where you'll find some tips on how to improve it.
2. Python, Sphinx or PyDoctor-Generated Documentation
Use http://pypi.python.org/pypi/doc2dash to generate docsets from Python, Sphinx or PyDoctor-generated documentation. When you're done generating your docset, scroll down to the bottom of this page where you'll find some tips on how to improve it.
3. Javadoc-Generated Documentation
Use https://github.com/Kapeli/javadocset to generate docsets from Javadoc-generated documentation. When you're done generating your docset, scroll down to the bottom of this page where you'll find some tips on how to improve it.
4. RDoc-Generated Documentation
You can use the “Ruby Installed Gems” docset, which is able to automatically index any RDoc-generated documentation you point it at. Install it from Preferences > Downloads.
5. Scaladoc-Generated Documentation
Use https://bitbucket.org/inkytonik/mkscaladocset to generate docsets from Scaladoc-generated documentation. When you're done generating your docset, scroll down to the bottom of this page where you'll find some tips on how to improve it.
6. Source Files: C, C++, C#, Objective-C, Java, PHP, Python etc.

Doxygen can generate docsets from source files of C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.

These are the entries you need to add into your Doxygen config file to make it generate a docset (note: the last 3 entries are optional):

GENERATE_DOCSET   = YES
DISABLE_INDEX     = YES 
SEARCHENGINE      = NO
GENERATE_TREEVIEW = NO
When Doxygen is done generating the documentation, run make inside the generated folder. Afterwards, scroll down to the bottom of this page where you'll find some tips on how to improve your docset.
7. Any HTML Documentation

Docsets are essentially just a folder containing the documentation and a SQLite database that indexes the files.

Instructions:

1. Create the Docset Folder

The docset folder structure can be created using this Terminal command:

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

You can also manually create the docset structure if you want, they're just folders.
2. Copy the HTML Documentation
Copy the HTML documentation you already have in the <docset name>.docset/Contents/Resources/Documents/ folder.
3. Create the Info.plist File
Download and edit this sample Info.plist and place it in the <docset name>.docset/Contents/ folder. Editing should be straightforward, just set the values to whatever name you want for your docset.
4. Create the SQLite Index

Create a SQLite database in the file <docset name>.docset/Contents/Resources/docSet.dsidx with the following query:

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

Recommended: you can easily prevent adding duplicate entries in the index by also using this query:

CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);
5. Populate the SQLite Index

You need to create a script (or application or whatever) that will go through your HTML documentation and add appropriate rows into the SQLite database. Rows can be added using this query:

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

The values are:

  • 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 “Class”. For a list of types that Dash recognises, see below.
  • path is the relative path towards the documentation file you want Dash to display for this entry. It can contain an anchor (#). Alternatively, Dash also supports http:// URL entries.
Supported Entry Types
Attribute
Binding
Category
Class
Command
Constant
Constructor
Define
Directive
Element
Entry
Enum
Error
Event
Exception
Field
File
Filter
Framework
Function
Global
Guide
Instance
Interface
Library
Macro
Method
Mixin
Module
Namespace
Notation
Object
Operator
Option
Package
Parameter
Property
Protocol
Record
Sample
Section
Service
Struct
Style
Tag
Trait
Type
Union
Value
Variable

Generation script examples:

1. Python
See https://github.com/datasaur/pgdash.
2. Ruby
See https://github.com/hpyhacking/erlang-docset.
3. Objective-C
See https://github.com/Kapeli/javadocset.
4. Node.js
See https://github.com/exlee/d3-dash-gen.

Improve a docset by:

1. Hosting a Docset Feed

Documentation feeds allow Dash users to conveniently install and update docsets. If you want to distribute a docset, it's highly recommended you set up a feed for it, so that you'll be able to update it in the future.

Dash documentation feeds are very simple, check one out at http://kapeli.com/feeds/NodeJS.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, use the following command:

tar --exclude='.DS_Store' -cvzf <docset name>.tgz <docset name>.docset
Currently only one docset per feed is supported (only one <entry>).
2. Sharing Docset Feeds

You can share docset feeds using a custom URL scheme, which will cause Dash to subscribe to that feed with a single click.

dash-feed://<URL encoded feed URL>

By URL encoded, I mean percent-encoding (e.g. what you’d get by clicking the encode button here).

Examples:

3. Setting an Index Page

Dash displays an index page when you highlight a docset in the documentation browser. If Dash can’t find a suitable index page automatically, you can specify it inside the Info.plist by adding the following entry:

<key>dashIndexFilePath</key>
<string>index.html</string>

The path can also be a http:// URL.

After adding the index, remove and re-add the docset in Dash’s Preferences.
4. Adding an Icon

To set a custom icon for your docset, simply add a "icon.png" file directly inside the docset bundle. For example, the file path would be <docset name>.docset/icon.png. The size of the icon should be 16x16, but Dash will scale down icons of any size. For Retina-display support, use a multi-resolution TIFF (with the sizes 16x16 and 32x32), or a 32x32 PNG.

After adding the icon, remove and re-add the docset in Dash’s Preferences.
5. Enabling JavaScript

By default, Dash does not allow external .js scripts. You can enable them by adding this entry to the docset’s Info.plist:

<key>isJavaScriptEnabled</key><true/>
After adding this entry, remove and re-add the docset in Dash’s Preferences.