Есть ли способ включить математические формулы в Scaladoc?

Я хотел бы ввести математические формулы в документацию Scaladoc математического кода Scala. В Java я нашел библиотеку под названием LatexTaglet, которая может сделать именно это для Javadoc, написав формулы в Latex: http://latextaglet.sourceforge.net/

И, похоже, он хорошо интегрируется с Maven (раздел отчетов/плагинов POM). Есть ли эквивалентная библиотека для Scaladoc? Если нет, как я могу интегрировать эту библиотеку с SBT?

Я также рассматривал использование MathML (http://www.w3.org/Math/), но выглядит слишком много. Есть ли редактор, который вы бы порекомендовали? MathML хорошо интегрируется с Scaladoc?

Благодарим за помощь!

Ответы

Ответ 1

Короткий ответ: нет. LaTeXTaglet становится возможным благодаря API JavaDoc Taglet. В Scaladoc нет эквивалента, поэтому нет чистого решения.

Однако я могу думать о хаке, который может быть достаточно простым:

Там есть библиотека под названием MathJax, которая ищет математические формулы в стиле LaTeX на странице HTML и динамически отображает ее на месте. Я использовал его раньше, это довольно хорошо; все, что вам нужно сделать, это включить script. Таким образом, вы могли бы сделать две вещи:

  • Отредактируйте и перестройте источник Scaladoc, чтобы включить MathJax или...
  • Запишите небольшой постпроцессор, сканирующий весь вывод HTML-кода Scaladoc после его запуска, и добавьте MathJax в каждый файл.

Таким образом, вы можете просто написать формулы LaTeX непосредственно в своих комментариях Scala, и они должны отображаться в браузере. Конечно, если вы хотите не-хакерское решение, я бы предложил вам создать теглет-подобный API для Scaladoc;)

Ответ 2

Чтобы следить за @mergeconflict answer, вот как я это сделал

Поскольку нет правильного решения, я сделал для реализации искателя, который анализирует все сгенерированные html файлы и заменяет любой найденный "тег импорта" (см. код ниже), путем импорта MathJax script:

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

Теперь можно было бы улучшить этот код. Например:

  • добавьте импорт script в раздел html head
  • не читать все файлы (возможно, добавить правило, что тег импорта должен быть в первых нескольких строках
  • добавьте script в пакет sbt и добавьте его в папку target/api с помощью подходящей задачи

Ответ 3

В готовящейся scala3, известной как Dotty, есть встроенная поддержка уценки, которая позволяет отображать простые математические формулы с использованием подмножества Latex.