Is there a way to include math formulae in Scalado

Question

I would like to enter math formulae in Scaladoc documentation of mathematical Scala code. In Java, I found a library called LatexTaglet that can do exactly this for Javadoc, by writing formulae in Latex: http://latextaglet.sourceforge.net/

And it seems to integrate well with Maven (reporting/plugins section of a POM). Is there an equivalent library for Scaladoc? If not, how could I integrate this library with SBT?

I also considered using MathML (http://www.w3.org/Math/), but looks too verbose. Is there an editor you would recommend? Does MathML integrate well with Scaladoc?

Thank you for your help!

Answer 1

The short answer is: no. LaTeXTaglet is made possible by the JavaDoc Taglet API. There is no equivalent in Scaladoc, therefore no clean solution.

However, I can think of a hack that might be easy enough to do:

There's a library called MathJax, which looks for LaTeX-style math formulae in an HTML page and dynamically renders it in place. I've used it before, it's pretty nice; all you have to do is include the script. So you could do two things:

1. Edit and rebuild the Scaladoc source to include MathJax, or...
2. Write a little post-processor crawl all of Scaladoc's HTML output after it runs, and inject MathJax into each file.

That way, you could just write LaTeX formulae directly in your Scala comments and they should be rendered in the browser. Of course if you wanted a non-hacky solution, I'd suggest you create a taglet-like API for Scaladoc ;)

Answer 2

To follow on @mergeconflict answer, here is how I did it

As there is no proper solution, what I did is to implement a crawler that parse all generated html files, and replace any found "import tag" (see code below), by the import of the MathJax script:

lazy val mathFormulaInDoc  = taskKey[Unit]("add MathJax script import in doc html to display nice latex formula")

mathFormulaInDoc := {
  val apiDir = (doc in Compile).value
  val docDir = apiDir    // /"some"/"subfolder"  // in my case, only api/some/solder is parsed
  // will replace this "importTag" by "scriptLine
  val importTag  = "##import MathJax"
  val scriptLine = "<script type=\"text/javascript\" src=\"https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML\"> </script>"
  // find all html file and apply patch
  if(docDir.isDirectory)
    listHtmlFile(docDir).foreach { f =>
      val content = Source.fromFile(f).getLines().mkString("\n")
        if(content.contains(importTag)) {
          val writer = new PrintWriter(f)
          writer.write(content.replace(importTag, scriptLine))
          writer.close()
        }
    }
}

// attach this task to doc task
mathFormulaInDoc <<= mathFormulaInDoc triggeredBy (doc in Compile)

// function that find html files recursively
def listHtmlFile(dir: java.io.File): List[java.io.File] = {
  dir.listFiles.toList.flatMap { f =>
    if(f.getName.endsWith(".html")) List(f)
    else if(f.isDirectory)          listHtmlFile(f)
    else                            List[File]()
  }
}

As you could see, this crawler task is attached to the doc task, to it is done automatically by sbt doc.

Here is an example of doc that will be rendered with formula

/**
 * Compute the energy using formula:
 *
 * ##import MathJax
 *
 * $$e = m\times c^2$$
 */
def energy(m: Double, c: Double) = m*c*c 

Now, it would be possible to improve this code. For example:

• add the script import in the html head section
• avoid reading the whole files (maybe add a rule that the import tag should be in the first few lines
• add the script to the sbt package, and add it to the target/api folder using some suitable task