有没有办法在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回答,我就是这样做的

由于没有适当的解决方案,我所做的是实现一个爬虫程序,解析所有生成的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 2

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

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

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

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

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