朱莉娅：docstrings和LaTeX

Question

Julia拥有docstrings个功能，这些功能在此处记录https://docs.julialang.org/en/stable/manual/documentation/。我的印象是它支持LaTeX代码，但我不确定LaTeX代码应该看起来像代码还是像解释一样。在下文中，LaTeX代码有点乱码（例如参见rho）并且没有解释（rho看起来不像ρ）。难道我做错了什么？

有没有办法让LaTeX代码看起来被解释？

我所说的解释就像他们在https://math.stackexchange.com/所做的那样。

文档说LaTeX代码应该用双引号括起来，希腊字母应该输入ρ而不是\rho。但这相当于能够包含LaTeX代码，这不是吗？

注意：版本0.5.2在Juno / Atom控制台中运行。

"""

Module blabla

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

"""
module blabla
end

如果我然后执行模块和查询我得到这个：

对于三重引号，美元符号消失，但公式印在黑暗的背景上：

编辑 David P. Sanders关于使用Documenter.jl包的建议的后续行动。

    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

给出以下内容：LaTeX代码似乎正确打印，但未被解释（ρ显示为\rho。我按照以下建议进行操作：https://juliadocs.github.io/Documenter.jl/stable/man/latex.html至

Answer 1

渲染LaTeX代码作为实际方程必须由任何软件呈现您的文档字符串。因此，简单回答你为什么在Juno中没有看到任何渲染方程式的原因是Juno目前不支持LaTeX渲染（正如Matt B.指出的那样，有一个open issue for that）。

doc""字符串文字/字符串宏可以解决另一个问题。反斜杠和美元符号在字符串文字中通常具有特殊含义 - escape sequences和{分别为{3}}（例如\n被替换为换行符，$(variable)将variable的值插入字符串中）。当然，这与普通的LaTeX命令和分隔符（例如\frac，$...$）冲突。因此，要在字符串中实际使用反斜杠和美元符号，您需要使用反斜杠将它们全部转义，例如：

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

不这样做会导致错误：

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

或结果字符串中的无效字符：

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

当编写文档字符串时，当然必须一直逃避所有事情。因此，为了解决这个问题，正如David指出的那样，您可以使用doc字符串宏/非标准字符串文字。在doc字面值中，忽略所有标准转义序列，因此未转义的LaTeX字符串不会导致任何问题：

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

注意：doc还解析字符串中的Markdown并实际返回一个Base.Markdown.MD对象，而不是字符串，这就是打印字符串与输入略有不同的原因。< / em>的

最后，您可以将这些doc - 文字用作普通的文档字符串，但是您可以随意使用LaTeX语法而无需担心转义所有内容：

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

这也记录在variable interpolation中，尽管它实际上并不特定于Documenter。

双重反对与美元符号。在Julia文档字符串或文档中标记LaTeX的首选方法是使用Documenter's manual或double backticks，如手册中所述。支持美元符号以实现向后兼容。

注意：应更新文件管理员手册和Julia中Markdown对象的show方法以反映这一点。

Answer 2

您可以使用

doc"""
    ...
"""

这是Documenter.jl包使用的“非标准字符串文字”;见https://docs.julialang.org/en/stable/manual/strings/#non-standard-string-literals。