有没有办法在Scaladoc中包含数学公式？

Question

我想在数学Scala代码的Scaladoc文档中输入数学公式。在Java中，我找到了一个名为LatexTaglet的库，通过在Latex中编写公式，可以为Javadoc做到这一点：http://latextaglet.sourceforge.net/

它似乎与Maven（POM的报告/插件部分）很好地集成。是否有Scaladoc的等效库？如果没有，我怎么能将这个库与SBT集成？

我也考虑使用MathML（http://www.w3.org/Math/），但看起来太冗长了。你会推荐一个编辑吗？ MathML是否与Scaladoc很好地集成？

谢谢您的帮助！

Answer 1

最简洁的答案是不。 LaDXTaglet是由JavaDoc Taglet API实现的。 Scaladoc中没有等效的，因此没有干净的解决方案。

但是，我可以想到一个可能很容易做到的黑客攻击：

有一个名为MathJax的库，它在HTML页面中查找LaTeX样式的数学公式并动态呈现它。我以前用过它，它很漂亮;你所要做的就是包括脚本。所以你可以做两件事：

1. 编辑并重建Scaladoc源以包含MathJax，或者......
2. 在运行Scaladoc的HTML输出后写一点后处理器，并将MathJax注入每个文件。

这样，您可以直接在Scala注释中编写LaTeX公式，并且应该在浏览器中呈现它们。当然，如果你想要一个非hacky解决方案，我建议你为Scaladoc创建一个类似taglet的API;）

Answer 2

继续关注@mergeconflict answer，我就是这样做的

由于没有合适的解决方案，我所做的是实现一个爬虫程序，解析所有生成的html文件，并通过导入MathJax脚本替换任何找到的“import tag”（参见下面的代码）：

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]()
  }
}

如您所见，此爬虫任务附加到doc任务，由sbt doc自动完成。

以下是将使用公式呈现的doc示例

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

现在，可以改进此代码。例如：

• 在html head部分添加脚本导入
• 避免读取整个文件（可能会添加一个规则，导入标记应该在前几行中
• 将脚本添加到sbt包，并使用一些合适的任务将其添加到target / api文件夹

Answer 3

即将推出的scala3 aka Dotty有in-built support for markdown，它允许使用Latex的子集渲染简单的数学公式。