且构网

分享程序员开发的那些事...
且构网 - 分享程序员编程开发的那些事

朱莉娅:docstrings和LaTeX

更新时间:2023-12-05 19:21:40

无论哪种软件呈现您的文档字符串,都必须将LaTeX代码呈现为实际方程式.因此,为什么您在Juno中看不到任何渲染方程式的简短答案是Juno当前不支持LaTeX渲染(正如Matt B.指出的那样,有一个

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).

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

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, ***es 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}$

不这样做会产生错误:

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

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

or invalid characters in the resulting strings:

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

编写文档字符串时,必须始终逃避所有麻烦.因此,要解决此问题,正如David指出的那样,可以使用doc字符串宏/非标准字符串文字.在doc文字中,所有标准转义序列都将被忽略,因此未转义的LaTeX字符串不会引起任何问题:

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}
$$

注意:doc还会解析字符串中的Markdown并实际上返回Base.Markdown.MD对象,而不是字符串,这就是为什么打印的字符串与输入有所不同的原因.

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.

最后,您可以将这些doc -literals用作常规文档字符串,但随后您可以***使用LaTeX语法而不必担心转义所有内容:

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.

双引号与美元符号.在Julia文档字符串或文档中标记LaTeX的首选方法是使用 ```math,如手册​​中所述.支持美元符号以实现向后兼容性.

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.

注意:应该更新文档手册和Julia中Markdown对象的show方法以反映这一点.

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