JuliaDocs/Documenter.jl

Improve warning when there are $ in doc strings / .md files in Documenter 1.0

Open

#2,288 建立於 2023年9月30日

在 GitHub 查看
 (6 留言) (0 反應) (0 負責人)Julia (910 star) (513 fork)batch import
Topic: UsabilityType: Enhancementhelp wanted

描述

I was a bit uncareful with my LaTeX writing in the doc strings and the markdown files, cf. e.g.

https://github.com/JuliaManifolds/Manopt.jl/blob/0865eb8b3a9a6f937c0599354bd3bbbc4c5e6c6d/docs/src/solvers/ChambollePock.md?plain=1#L6

While the “old” Documenter (pre 1.0) was quite fine with this (or tolerant to $...$ LaTeX, now one gets the warning

┌ Warning: Unexpected Julia interpolation of type Symbol in the Markdown.
│   value = :p
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/9kOxY/src/html/HTMLWriter.jl:2215

(which luckily someone hunted down for me to the above line). I think that warning could maybe improved? It also seems that this does not always happen … so maybe also only for $ in Doc strings but not in md files? The reason I assume that is, that some of my Markdown files are generated by Quarto before the Documenter run – that Markdown contains (for laziness and Quarto/Pandoc preferring $...$) normal LaTeX, and that renders without warning.

Sorry if this is a bit vague, but I am still not 100% sure how to reproduce this.

貢獻者指南