Julia: docstrings and LaTeX

Question

Julia has docstrings capabilities, which are documented here https://docs.julialang.org/en/stable/manual/documentation/. I'm under the impression that it has support for LaTeX code, but I'm not sure if the intention is that the LaTeX code should look like code or like an interpretation. In the following, the LaTeX code is garbled somewhat (see rho, for instance) and not interpreted (rho does not look like ρ). Am I doing something wrong?

Is there a way to get LaTeX code look interpreted?

What I mean by interpreted is something like what they do at https://math.stackexchange.com/.

The documentation says that LaTeX code should be wrapped around double back-quotes and that Greek letters should be typed as ρ rather than \rho. But that rather defeats the point of being able to include LaTeX code, doesn't it?

Note: Version 0.5.2 run in Juno/Atom console.

"""

Module blabla

The objective function is:
``\max \mathbb{E}_0 \int_0^{\infty} e^{-\rho t} F(x_t) dt``

"""
module blabla
end

If I then execute the module and query I get this:

With triple quotes, the dollar signs disappear, but the formula is printed on a dark background:

EDIT Follow-up to David P. Sanders' suggestion to use the Documenter.jl package.

    using Documenter
    doc"""
    Module blabla

    The objective function is:
    $\max \mathbb{E}_0 \int_0^{\infty} e^{-\rho t} F(x_t) dt$
    """
    module blabla
    end

Gives the following: the LaTeX code appears to print correctly, but it's not interpreted (ρ is displayed as \rho. I followed suggestions in: https://juliadocs.github.io/Documenter.jl/stable/man/latex.html to

Answer 1

Rendering LaTeX code as actual equations has to be supported by whichever software renders your docstrings. So, the short answer to why you're not seeing any rendered equations in Juno is that LaTeX rendering is currently not supported in Juno (as Matt B. pointed out, there's an open issue for that).

The doc"" string literal / string macro is there to get around another issue. Backslashes and dollar signs normally have a special meaning in string literals -- escape sequences and variable interpolation, respectively (e.g. \n gets replaced by a newline character, $(variable) inserts the value of variable into the string). This, of course, clashes with the ordinary LaTeX commands and delimiters (e.g. \frac, $...$). So, to actually have backslashes and dollar signs in a string you need to escape them all with backslashes, e.g.:

julia> "\$\\frac{x}{y}\$" |> print
$\frac{x}{y}$

Not doing that will either give an error:

julia> "$\frac{x}{y}$" |> print
ERROR: syntax: invalid interpolation syntax: "$\"

or invalid characters in the resulting strings:

julia> "``\e^x``" |> print
``^x``

Having to escape everything all the time would, of course, be annoying when writing docstrings. So, to get around this, as David pointed out out, you can use the doc string macro / non-standard string literal. In a doc literal all standard escape sequences are ignored, so an unescaped LaTeX string doesn't cause any issues:

julia> doc"$\frac{x}{y}$" |> print
$$
\frac{x}{y}
$$

Note: doc also parses the Markdown in the string and actually returns a Base.Markdown.MD object, not a string, which is why the printed string is a bit different from the input.

Finally, you can then use these doc-literals as normal docstrings, but you can then freely use LaTeX syntax without having to worry about escaping everything:

doc"""
$\frac{x}{y}$
"""
function foo end

This is also documented in Documenter's manual, although it is not actually specific to Documenter.

Double backticks vs dollar signs. The preferred way to mark LaTeX in Julia docstrings or documentation is by using double backticks or ```math blocks, as documented in the manual. Dollar signs are supported for backwards compatibility.

Note: Documenter's manual and the show methods for Markdown objects in Julia should be updated to reflect this.