Docstrings rendering and math inside them (with Documenter)

[kellertuer]

If you have math in a doc string, the compilation might fail, cf for example this line

https://github.com/JuliaManifolds/Manopt.jl/blob/74d873109c2fbc857a55b445ed78548702e89bf2/examples/FrankWolfeSPDMean.jl#L55-L67

The reason is that the rendering is encapsulated in

```@raw html
```

so the end of the math environment line ends the raw html making the rendering from markdown to html look very strange.

For now – sure – I can fix that locally by taking four or more backticks for the math environment.

Finally, in Pluto itself the cell with a function definition with a doctoring nicely renders the doctoring of the function as an output, while StaticPlutoHTML does not (no output cell) – any idea why this might be the case?

[rikhuijzer]

so the end of the math environment line ends the raw html making the rendering from markdown to html look very strange.

Ah so probably the backticks should be escaped? Would you know how such a backtick can be spotted. Should escaping any backtick in the Markdown work, you think?

For now – sure – I can fix that locally by taking four or more backticks for the math environment.

Ah that's good to hear that it is reasonably easy to fix on your side.

Finally, in Pluto itself the cell with a function definition with a doctoring nicely renders the doctoring of the function as an output, while StaticPlutoHTML does not (no output cell) – any idea why this might be the case?

Ah that's a special case that they've implemented at Pluto's side. It's not really put in Pluto's "output", right? It's a separate thing. Or at least that's what I think it is doing; I have never looked at that code.

[kellertuer]

so the end of the math environment line ends the raw html making the rendering from markdown to html look very strange.

Ah so probably the backticks should be escaped? Would you know how such a backtick can be spotted. Should escaping any backtick in the Markdown work, you think?

Maybe that helps, I am not sure

For now – sure – I can fix that locally by taking four or more backticks for the math environment.

Ah that's good to hear that it is reasonably easy to fix on your side.

The only disadvantage is, that one has to find the number of ticks the HTML export does not use ;)

Finally, in Pluto itself the cell with a function definition with a doctoring nicely renders the doctoring of the function as an output, while StaticPlutoHTML does not (no output cell) – any idea why this might be the case?

Ah that's a special case that they've implemented at Pluto's side. It's not really put in Pluto's "output", right? It's a separate thing. Or at least that's what I think it is doing; I have never looked at that code.

I am not sure what they do there, but defining a function (see also the link above it contains a few examples) and allowing output (i.e. not putting a ; at the end) renders the doc-string (as if the cell were just a markdown string but additionally with a function name in the top left).