JuliaDocs/Documenter.jl

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

开放

#2,288 创建于 2023年9月30日

 (6 条评论) (0 个反应) (0 位负责人)Julia (513 个派生)batch import
Topic: UsabilityType: Enhancementhelp wanted

仓库指标

星标
 (910 个星标)
PR 合并指标
 (平均合并 16天 9小时) (30 天内合并 3 个 PR)

描述

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.

贡献者指南