Note: Dash 2 can automatically create documentation sets from published Scala documentation in the Maven Central repository. (See the Downloads tab of the Preferences dialog.) If you are interested in that kind of doc set you will probably find that method easier to use than using
mkScalaDocset is a script and accompanying Scala code to build documentation
sets for the Dash documentation browser from documentation
that has been produced by ScalaDoc.
- Standard Unix scripting programs: shell (sh), make, dirname, etc
- Scala (scalac compiler and scala runner)
The current version has been tested on Mac OS X 10.8.2 where greadlink was installed using the Homebrew coreutils package and we used Scala 2.9.2 (also installed from Homebrew).
The script assumes that you already have a set of documentation that has been
produced by ScalaDoc. E.g., if your project is built using sbt and the code
contains ScalaDoc comments, you can generate the documentation using the
sbt doc command. sbt will put the documentation in the directory
in your project, where
<version> is the Scala version.
Check out this repository and run the following command in it:
This command will compile the conversion program and put its class
files in the
target sub-directory where they can be found by the
conversion script. You can run "make clean" to remove these
generated class files and the
Run the script as follows:
mkScalaDocset <name> <docdir>
<name> is the name that you want to use for the documentation set.
This name will also be used to define the bundle identifier and documentation
<docdir> should be the top-level directory of the
ScalaDoc-generated documentation. E.g., you might run the script like this:
mkScalaDocset MyProject /path/to/myproject/target/scala-2.9.2/api
The script will produce the docset in
<name>.docset in your current
directory. You can add it to the docsets used by your Dash browser using
the Docsets tab of the Dash preferences window.
The script also supports optional arguments which can appear after the two required arguments. The optional arguments must be of the following forms:
file.pngas the icon to identify this docset in the browser.
file.htmlas the index file to display when the top level of this docset is selected in the browser. The file name is interpreted relative to the top of
mkScalaDocset uses the Scala
XHtmlParser class to parse the documentation
files, so it expected files to be XHTML compliant (at least according to
mkScalaDocset will do its best to report errors, but
XHtmlParser doesn't provide detailed error locations so
tracking down why a message appears can be hard.
For example, the following message from
mkScalaDocset tells you what is
wrong but not where
GenDBCommands: failed to parse 'MyTool.docset/Contents/Resources/Documents/mytool-1.0.1/scala/mytool/mycode.html' expected closing tag of p
If you get this sort of error and still want to use
mkScalaDocset you will
need to tidy up the documentation files first. Sometimes this can be done by
fixing the Scala source code from which the documentation has been generated.
Make sure that any inline HTML in the code documentation is XHTML compliant.
It is not necessarily the case that the ScalaDoc tool will generate
documentation files that can be processed automatically by mkScalaDocset.
Sometimes this is because ScalaDoc generates HTML for browsers, not
necessarily XHTML for tools like mkScalaDocset. Also, ScalaDoc does have some
bugs that cause strange output to be produced. If you see one of these
problems, your main recourse will be to manually fix the files before
Tony Sloane Berk Demir Duyang Zhou
Thanks to Kapeli for providing information about their existing support for indexing Scala documentation sets on which this software was based. Instructions for making documentation sets from a variety of sources can be found at Kapeli's documentation site.