HTTPS SSH

mkScalaDocset

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.

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.

Tony Sloane, inkytonik@gmail.com

Requirements

  • Standard Unix scripting programs: shell (sh), make, dirname, etc
  • greadlink
  • 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

 target/scala-<version>/api

in your project, where <version> is the Scala version.

Installation

Check out this repository and run the following command in it:

make

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 target folder.

Usage

Run the script as follows:

mkScalaDocset <name> <docdir>

where <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 platform family. <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:

  • icon=file.png: use file.png as the icon to identify this docset in the browser.

  • index=file.html: use file.html as 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 <docdir>.

Possible problems

mkScalaDocset uses the Scala XHtmlParser class to parse the documentation files, so it expected files to be XHTML compliant (at least according to XHtmlParser). mkScalaDocset will do its best to report errors, but unfortunately 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 running mkScalaDocset.

Contributors

Tony Sloane Berk Demir Duyang Zhou

Acknowledgements

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.