Generate Scala API docs without JavaScript, but static HTML or Markdown

Question

For an in-application help browser, I would like to render API docs. Unfortunately, Scaladoc seems to produce only HTML files full of horrible JavaScript stuff, so it's impossible to render these files even with rather heavy weight components such as SwingBox (which does have very good CSS though).

So my question is: Can I leverage the Scaladoc tool or its API (if there is any) to generate some intermediate representation which I can then write out into, say, custom Markdown files or static HTML pages?

Bond

Answer 1

What you are looking for is a custom Doclet implementation, which can be used through the -doc-generator command-line option to scaladoc. I can't answer whether or not a pre-existing Doclet implementation will address your needs, but one promising implementation to explore is Extradoc. However, it hasn't been updated in some time.

At a lower level you can implement your own by subclassing Doclet and associated APIs (e.g. HTMLFactory, and Template). There don't seem to be any/many examples out there of how to do this beyond Extradoc¹. Unfortunately it looks like ScalaDoc hasn't gotten the same level of attention as JavaDoc in this area. Per these release notes, 2.12 has an improved ScalaDoc interface, but I don't think it changes the dependency on JavaScript.

I also came across Nyandoc, which converts ScalaDoc and JavaDoc to Markdown. Perhaps as an immediate format it could get you closer to your goal.

All that said, is using the JavaFX WebView component an option? It has a full fledged WebKit browser and JS engine behind it, and it's possible to embed JavaFX components in Swing.

Oversold

Thanks, that's a bunch of useful links. I wasn't aware of Doclet or Nyandoc and will see if they can be used. Right now I don't want to require Java 8/JavaFX/WebView, also because I would like to tune the markdown in different ways. – Bond

Understandable on Java 8 and the desire to tune the output. Just note that JavaFX 2 runs on Java 7, and it too has WebView. – Oversold

I see. The legacy system I still try to satisfy is some old OS X 10.6 snow leopard boxes that cannot run anything newer than Java 6. (Also on Linux, I would have to check that OpenJFX 2 runs on OpenJDK 7) – Bond