LaTeX Docstrings

[ChrisRackauckas]

Hey, I am having issues getting the LaTeX from the docstrings to display. For example, following the Julia documentation documentation, I use the following docstring:

doc"""
HeatProblem

Wraps the data that define a 2D linear heat equation problem:

`` $$ u_t = Δu + f(x,t) $$ ``

(truncated for simplicity). In my documentation I use {docs} HeatProblem which transforms into Markdown code like

HeatProblem

Wraps the data that define a 2D linear heat equation problem:

`` $ (generic function with 34 methods) u_t = Δu + f(x,t) $ (generic function with 34 methods) ``

And using

deploydocs(deps   = Deps.pip("mkdocs", "python-markdown-math"),
    repo = "github.com/ChrisRackauckas/DifferentialEquations.jl.git",
    julia  = "0.4.5",
    osname = "linux")

to build I get results that can be seen at the documentation here. Is there way to get the LaTeX to render?

[MichaelHatherly]

Double backtick syntax for LaTeX is only supported in 0.5, not sure why the 0.4 manual mentions it, probably backported unintentionally with the rest of the style guide updates.

On 0.4 you should use single $s for maths, i.e.

"""
Inline maths \$x\$.

Block equations:

\$x\$

"""
# ...

(Note the blank lines above and below the block equation.)

On 0.5 the double backtick syntax was added to avoid having to deal with escaping $s, which conflicts with interpolation syntax. Block equations use normal fenced code blocks with the language set as math.

"""
Inline maths ``x``.

Block equations:

```math
x
```
"""
# ...

So if you've got docs in Julia 0.4 then for the moment use the $ syntax, which is supported in both 0.4 and 0.5. If it's just 0.5 then use the backtick syntax, which will be the way forward in Julia's flavour of markdown.

[ChrisRackauckas]

Thanks for the info. Couldn't find this documented anywhere else, but it clears everything up.

[ChrisRackauckas]

Just to clarify: does Julia Markdown work in Documenter.jl? So for my documentation (not just docstrings, like in other .md files), I should use double backticks and triple backtick math?

[MichaelHatherly]

Yes, docstrings and external markdown files are parsed using the same function, Base.Markdown.parse, which Documenter.jl uses. Double backticks and triple backtick math for Julia 0.5, and $ for Julia 0.4. Backticks will gracefully fallback to displaying as code fragments on 0.4 so shouldn't look too bad there.

[IainNZ]

So is there are way to do use multiline equations on Julia 0.4 with Documenter.jl + mkdocs? I'm struggling to figure out the incantation.

[MichaelHatherly]

Since JuliaLang/julia#15545 hasn't been backported (perhaps it should), here's what's needed to get multiline equations displayed properly:

Add the Markdown.plain method from that PR to docs/make.jl

function Base.Markdown.plain(io::IO, l::Base.Markdown.LaTeX)
    println(io, '$', '$')
    println(io, l.formula)
    println(io, '$', '$')
end

Install the Python markdown maths extension with pip install python-markdown-math otherwise equations end up being displayed weirdly sometimes. Also add it to the mkdocs.yml file with

...
markdown_extensions:
  ...  
  - mdx_math
  ...

Use single $ wrapping the multiline equation with blank lines above and below the entire equation block:

"""
...

\$\\left\\{\\begin{aligned} 
\\frac{a}{b}&=\\frac{c}{d}\\\\
\\frac{e}{f}&=\\frac{h}{i}
\\end{aligned}\\right.\$

...
"""
f(x) = ...

That should display properly on 0.4.

[IainNZ]

I was actually asking about just plain .md files I was using for my docs, not even for docstrings (although that looks amazingly painful to have to double slash everything in docstrings). Or is the same for .md files?

[IainNZ]

Maybe an example of how to properly to do math somewhere in the Documenter docs would help me, I'm kind of baffled as to what mangling is taking place right now. Trying to bring over docs from Judo.jl style.

[MichaelHatherly]

For .md files the \ escapes aren't needed. In docstrings you can use the doc"" macro to avoid the escapes as well. Adding an example would be a good idea. I'll put one up tomorrow if I have time.

[MichaelHatherly]

I've added a basic guide, abf1c1c (http://michaelhatherly.github.io/Documenter.jl/latest/man/latex/), that describes how to add LaTeX support.

@IainNZ, if you've got a public repo/branch where docs are getting mangled then I'd be happy to take a look at it.