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:
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.
Doxygen can generate docsets from source files of C, C++, C#, PHP, Objective-C, Java, Python (and some others).
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 = NOWhen Doxygen is done generating the documentation, run
makeinside the generated folder. Afterwards, scroll down to the bottom of this page where you'll find some tips on how to improve your docset.
Docsets are essentially just a folder containing the documentation and a SQLite database that indexes the files.
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.
<docset name>.docset/Contents/folder. Editing should be straightforward, just set the values to whatever name you want for your docset.
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);
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:
nameis 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.
typeis 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.
pathis the relative path towards the documentation file you want Dash to display for this entry. It can contain an anchor (#). Alternatively, Dash also supports
Please contact me if none of the currently supported types are suitable for what you're trying to index.
To allow easy navigation inside a large page, Dash is able to show a table of contents at the bottom left. This feature is described in the user guide.
Please note that adding table of contents support is a bit tricky (and optional).
When Dash displays a documentation page, it also looks for special anchors inside the HTML and generates a table of contents. To add table of contents support, you need to go through all the HTML pages and insert anchors in a format that Dash understands.
The format for the anchors is:
<a name="//apple_ref/cpp/Entry Type/Entry Name" class="dashAnchor"></a>
The only things that you need to change in the format above are:
You can see an example of how to insert anchors at https://github.com/jkozera/zeal/blob/master/gendocsets/extjs/parse.py (in Python).
You'll also need to add a entry in the docset's Info.plist:
Generation script examples:
Improve a docset by:
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:
<version>element. You can use any versioning system you want. Dash will use string comparison to determine whether or not to download an update.
<url>elements. These point to the URL of the archived docset.
<sha1>element that contains the sha1 checksum of the archive. You can generate a sha1 checksum using
openssl sha1 docset.tgzin Terminal.
To archive your docset, use the following command:
tar --exclude='.DS_Store' -cvzf <docset name>.tgz <docset name>.docsetCurrently only one docset per feed is supported (only one
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:
The path can also be a
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. For Retina-display support, use a multi-resolution TIFF (with the sizes 16x16 and 32x32), or a 32x32 PNG. Please note that icons of any size will also work, but it's highly recommended that you provide the exact size (16x16 and 32x32), as otherwise searching the docset in Dash might be slowed down because the icons have to be resized.
By default, Dash does not allow external .js scripts. You can enable them by adding this entry to the docset’s Info.plist: