Czy istnieje sposób na uwzględnienie formuł matematycznych w Scaladoc?

Question

Chciałbym wprowadzić wzory matematyczne w dokumentacji Scaladoc matematycznego kodu Scala. W Javie, znalazłem biblioteki o nazwie LatexTaglet że może zrobić dokładnie to dla Javadoc, poprzez pisanie formuł w lateks: http://latextaglet.sourceforge.net/

I wydaje się, aby dobrze zintegrować z Maven (sekcja raportowania/wtyczki z POM). Czy istnieje odpowiednia biblioteka dla Scaladoc? Jeśli nie, jak mogę zintegrować tę bibliotekę z SBT?

Rozważałem także użycie MathML (http://www.w3.org/Math/), ale wygląda zbyt gadatliwie. Czy jest jakiś edytor, który polecasz? Czy MathML dobrze integruje się ze Scaladoc?

Dziękuję za pomoc!

Answer 1

Krótka odpowiedź brzmi: nie. LaTeXTaglet jest możliwe dzięki API JavaDoc Taglet. W Scaladoc nie ma odpowiednika, dlatego nie ma czystego rozwiązania.

Jednak mogę myśleć hack, które mogą być dość łatwe do zrobienia:

Istnieje biblioteka nazywa MathJax, który szuka LaTeX stylu formuł matematycznych na stronie HTML i dynamicznie renderuje go na miejscu. Używałem go wcześniej, to całkiem miłe; wszystko co musisz zrobić, to dołączyć skrypt. Więc można zrobić dwie rzeczy:

1. Edycja i odbudować źródło Scaladoc zawierać mathjax, albo ...
2. napisać trochę post-procesora pełzać wyjścia HTML Scaladoc po biegnie i wstrzyknąć do mathjax każdy plik.

W ten sposób można po prostu pisać formuły LaTeX bezpośrednio w komentarzach Scala i powinny być renderowane w przeglądarce. Oczywiście jeśli chciałeś non-hacky rozwiązanie, polecam utworzyć taglet podobny API dla Scaladoc;)

Answer 2

Aby śledzić na @mergeconflict answer, oto jak to zrobiłem

Ponieważ istnieje brak właściwego rozwiązania, co zrobiłem jest wdrożenie robota, który analizował wszystkie wygenerowane pliki html i zastąpić dowolny znaleziono „tag importu” (patrz kod poniżej), przez import skryptu 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]() 
    } 
} 

jak ty można zobaczyć, że to zadanie przeszukiwacza jest dołączone do zadania doc, aby zostało zrobione automatycznie przez sbt doc.

Oto przykład z dokumentu, które zostaną wykonane z wzorem

/** 
* Compute the energy using formula: 
* 
* ##import MathJax 
* 
* $$e = m\times c^2$$ 
*/ 
def energy(m: Double, c: Double) = m*c*c 

Teraz byłoby to możliwe, aby poprawić ten kod.Na przykład:

• dodać import skrypt w sekcji head html
• Unikaj czytania całych plików (może dodać regułę, że tag importu powinien znajdować się w pierwszych kilku liniach
• dodać skrypt do sbt i dodaj go do folderu docelowego/api za pomocą jakiegoś odpowiedniego zadania