scala - 有没有办法在 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

关注 @mergeconflict answer ，这是我如何做到的

由于没有合适的解决方案，我所做的是实现一个爬虫来解析所有生成的 html 文件，并通过导入 MathJax 脚本替换任何找到的“导入标签”(见下面的代码):

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 自动完成。 .

这是将使用公式呈现的文档示例

/**
 * 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 文件夹