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

我想在数学Scala代码的Scaladoc文档中输入数学公式。在Java中，我发现了一个名为LatexTaglet的库，它可以通过在Latex中编写公式来为Javadoc实现这一点：

而且它似乎与Maven（POM的报告/插件部分）集成得很好。Scaladoc是否有等效的库？如果没有，我如何将此库与SBT集成

我也考虑过使用MathML（），但看起来太冗长了。你会推荐一位编辑吗？MathML与Scaladoc集成得好吗

---

谢谢你的帮助

简单的回答是：不，LaTeXTaglet是由JavadocAPI实现的。Scaladoc中没有等效物，因此没有干净的溶液

然而，我能想到一个可能很容易做到的黑客：

有一个名为的库，它在HTML页面中查找LaTeX样式的数学公式，并动态地将其呈现到位。我以前用过，很不错；您所要做的就是包含脚本。所以你可以做两件事：

编辑并重新生成源代码以包含MathJax，或者

在Scaladoc运行后编写一个小的后处理器抓取所有的HTML输出，并将MathJax注入到每个文件中

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

接下来，我是这样做的

由于没有合适的解决方案，我所做的是实现一个爬虫程序来解析所有生成的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]()
  }
}

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

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

---

即将推出的scala3又称Dotty，它允许使用乳胶的子集绘制简单的数学公式。

我使用与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注释中的

  $

  或

  $$

  中
• 最好用另一个元素进一步将它们括在注释中。我一直在使用

• 至少对于Scala 2.11.x中包含的Scaladoc，公式只会显示在类、对象和特征的顶级符号上。当MathJax inject元素出现时，切换中的某些内容会显示完整的注释中断。我还没有弄清楚，但如果我弄清楚，我会直接向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 {

/**
*平均绝对标度误差的实现
*
*非季节性MASE公式：
* 
* $$
*\MathM{{{梅赛}}{{梅赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛赛左| Y | T-Y{T-1}\右|}
* $$
* 
**/
对象平均绝对缩放错误{

非常感谢您的回答！可能是SIP的一个想法？是否可以使用sbt（doc）来实现crowling，如果可以，如何实现？未来注意：cdn.mathjax.org即将结束，请查看迁移提示。@Choucri这应该是正确的答案，因为它告诉您可以实现它以及如何实现它。

/**
  * 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 {