Is there a way to include math formulae in Scaladoc?

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,

Answer 1

I solved this by using the same approach as Spark did.

Put this JavaScript in a file somewhere in your project:

// From Spark, licensed APL2
// https://github.com/apache/spark/commit/36827ddafeaa7a683362eb8da31065aaff9676d5

function injectMathJax() {
    var script = document.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.onload = function(){
        MathJax.Hub.Config({
            displayAlign: "left",
            tex2jax: {
                inlineMath: [ ["$", "$"], ["\\\\(","\\\\)"] ],
                displayMath: [ ["$$","$$"], ["\\[", "\\]"] ],
                processEscapes: true,
                skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'a']
            }
        });
    };
    script.src = ('https:' == document.location.protocol ? 'https://' : 'http://') +
        'cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML';
    document.getElementsByTagName('head')[0].appendChild(script);
}

document.addEventListener('DOMContentLoaded', injectMathJax)

and this little bit into your build.sbt:

lazy val injectMathJax = taskKey[Unit]("Injects MathJax Javascript into Scaladoc template.js")

injectMathJax := {
    val docPath = (Compile / doc).value
    val templateJsOutput = docPath / "lib" / "template.js"
    streams.value.log.info(s"Adding MathJax initialization to $templateJsOutput")
    // change this path, obviously
    IO.append(templateJsOutput, IO.readBytes(file("doc/static/js/mathjax_init.js")))
  },
  injectMathJax := (injectMathJax triggeredBy (Compile / doc)).value

I'll eventually get around to building and publicly releasing a plugin for this, as I'm likely going to be using Scala 2.x for a very long time.

Caveats to this approach:

• Formulae must be in $ or $$ in Scaladoc comments.
• It's best to further enclose them in the comment with another element. I've been using

  .

• For at least the Scaladoc included with Scala 2.11.x, a formula will only show on class, object, and trait top-level symbols. Something in the toggle to show the full comment breaks when MathJax-inject elements are present. I've not figured it out yet, but if I do, I'll submit a patch to Scaladoc directly.

Example:

/**
  * A Mean Absolute Scaled Error implementation
  *
  * Non-seasonal MASE formula:
  * 

  * $$
  * \mathrm{MASE} = \mathrm{mean}\left( \frac{\left| e_j \right|}{\frac{1}{T-1}\sum_{t=2}^T \left| Y_t-Y_{t-1}\right|} \right) = \frac{\frac{1}{J}\sum_{j}\left| e_j \right|}{\frac{1}{T-1}\sum_{t=2}^T \left| Y_t-Y_{t-1}\right|}
  * $$
  * 
 **/
object MeanAbsoluteScaledError {