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文件，并替换任何找到的＆＃34; import标签＆＃34; （参见下面的代码），通过导入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]()
  }
}

如您所见，此抓取工具任务已附加到文档任务，由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样式的数学公式并动态呈现它。我以前用过它，它很漂亮;你所要做的就是包括脚本。所以你可以做两件事：

编辑并重建Scaladoc来源以包含MathJax或......
在运行后编写一些稍后的处理器抓取Scaladoc的所有HTML输出，并将MathJax注入每个文件。

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

Answer 3

即将推出的scala3又名Dotty具有in-built support for markdown，它允许使用Latex的子集来呈现简单的数学公式。

Answer 4

我通过使用与Spark相同的方法解决了这个问题。

将此JavaScript放在项目中某个位置的文件中

// 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)

这一点进入您的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

我最终将为此构建并公开发布一个插件，因为我很可能会在很长一段时间内使用Scala 2.x。

该方法的注意事项：

公式必须在Scaladoc注释的$或$$中。
最好在注释中再加上另一个元素。我一直在使用<blockquote>。
至少对于Scala 2.11.x随附的Scaladoc，公式仅在类，对象和特征顶级符号上显示。当存在MathJax-inject元素时，切换框中的 Something 会显示完整的注释中断。我还没有弄清楚，但是如果这样做，我将直接向Scaladoc提交补丁。

示例：

/**
  * A Mean Absolute Scaled Error implementation
  *
  * Non-seasonal MASE formula:
  * <blockquote>
  * $$
  * \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|}
  * $$
  * </blockquote>
 **/
object MeanAbsoluteScaledError {

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

4 个答案: