C'è un modo per includere formule matematiche in Scaladoc?

Question

Vorrei inserire le formule matematiche nella documentazione Scaladoc del codice matematico Scala. In Java, ho trovato una libreria chiamata LatexTaglet che può fare esattamente questo per Javadoc, da formule che scrivono in lattice: http://latextaglet.sourceforge.net/

e sembra integrarsi bene con Maven (sezione di segnalazione/plugins di un POM). Esiste una libreria equivalente per Scaladoc? In caso contrario, come potrei integrare questa libreria con SBT?

Ho anche considerato l'utilizzo del MathML (http://www.w3.org/Math/), ma sembra troppo prolisso. C'è un editor che consiglieresti? MathML si integra bene con Scaladoc?

Grazie per il vostro aiuto!

Answer 1

La risposta breve è: no. LaTeXTaglet è reso possibile dall'API JavaDoc Taglet. Non esiste un equivalente in Scaladoc, quindi nessuna soluzione pulita.

Tuttavia, posso pensare a un hack che potrebbe essere abbastanza facile da fare:

C'è una libreria chiamata MathJax, che cerca formule matematiche LaTeX in stile in una pagina HTML e rende dinamicamente in posizione. L'ho usato prima, è molto carino; tutto ciò che devi fare è includere lo script. Così si potrebbe fare due cose:

1. Modifica e ricostruire la fonte Scaladoc per includere mathjax, o ...
2. scrivere un po 'di ricerca per indicizzazione post-processor tutte output HTML di scaladoc dopo l'esecuzione, e iniettare mathjax in ogni file.

In questo modo, è possibile scrivere le formule LaTeX direttamente nei commenti di Scala e devono essere visualizzate nel browser. Naturalmente se si voleva un non-hacky soluzione , io suggerirei di creare un'API taglet simile per scaladoc;)

Answer 2

da seguire su @mergeconflict answer, ecco come ho fatto

Poiché non v'è nessuna soluzione adeguata, quello che ho fatto è quello di implementare un cingolato che analizza tutti i file HTML generato, e sostituire le "tag di importazione" che si trova (vedi codice qui sotto), per l'importazione dello script 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]() 
    } 
} 

Come si potrebbe vedere, questa attività crawler è allegata all'attività doc, perché viene eseguita automaticamente da sbt doc.

Ecco un esempio di documento che verrà reso con formula

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

Ora, sarebbe possibile migliorare questo codice.Per esempio:

• aggiungere l'importazione di script nella sezione head html
• evitare di leggere i file interi (forse aggiungere una regola che il tag di importazione dovrebbe essere nelle prime righe
• aggiungere lo script al pacchetto sbt, e aggiungilo alla cartella target/api usando qualche compito adatto