Add option treat_markdown_warnings_as_error (#2792)

Author: aaruni96

CHANGELOG.md

@@ -5,6 +5,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+* Added option `treat_markdown_warnings_as_error` which throws an error when encountering a markdown/interpolation warning ([#2792], [#2751])
+
 ### Changed
 
 * Page category is removed from the search index and now everything is in section category. ([#2762], [#2413])
@@ -2161,13 +2165,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2737]: https://github.com/JuliaDocs/Documenter.jl/issues/2737
 [#2748]: https://github.com/JuliaDocs/Documenter.jl/issues/2748
 [#2750]: https://github.com/JuliaDocs/Documenter.jl/issues/2750
+[#2751]: https://github.com/JuliaDocs/Documenter.jl/issues/2751
 [#2753]: https://github.com/JuliaDocs/Documenter.jl/issues/2753
 [#2761]: https://github.com/JuliaDocs/Documenter.jl/issues/2761
 [#2762]: https://github.com/JuliaDocs/Documenter.jl/issues/2762
 [#2772]: https://github.com/JuliaDocs/Documenter.jl/issues/2772
 [#2773]: https://github.com/JuliaDocs/Documenter.jl/issues/2773
 [#2774]: https://github.com/JuliaDocs/Documenter.jl/issues/2774
 [#2787]: https://github.com/JuliaDocs/Documenter.jl/issues/2787
+[#2792]: https://github.com/JuliaDocs/Documenter.jl/issues/2792
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
 [JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

src/documents.jl

@@ -363,6 +363,7 @@ struct User
     highlightsig::Bool  # assume leading unlabeled code blocks in docstrings to be Julia.
     draft::Bool
     meta::Dict{Symbol, Any} # default @meta block data for pages
+    treat_markdown_warnings_as_error::Bool # option to treat markdown warnings as an error
 end
 
 """
@@ -426,6 +427,7 @@ function Document(;
         highlightsig::Bool = true,
         draft::Bool = false,
         meta::Dict{Symbol} = Dict{Symbol, Any}(),
+        treat_markdown_warnings_as_error::Bool = false,
         others...
     )
 
@@ -492,6 +494,7 @@ function Document(;
         highlightsig,
         draft,
         meta,
+        treat_markdown_warnings_as_error,
     )
     internal = Internal(
         assetsdir(),

src/html/HTMLWriter.jl

@@ -2436,19 +2436,23 @@ function domify(dctx::DCtx, node::Node, t::MarkdownAST.Table)
     )
 end
 
-function domify(::DCtx, ::Node, e::MarkdownAST.JuliaValue)
-    @warn(
-        """
-        Unexpected Julia interpolation in the Markdown. This probably means that you
-        have an unbalanced or un-escaped \$ in the text.
+function domify(dctx::DCtx, ::Node, e::MarkdownAST.JuliaValue)
+    message = """
+        Unexpected Julia interpolation in the Markdown. This probably means that you have an
+        unbalanced or un-escaped \$ in the text.
 
         To write the dollar sign, escape it with `\\\$`
 
         We don't have the file or line number available, but we got given the value:
 
         `$(e.ref)` which is of type `$(typeof(e.ref))`
-        """
-    )
+    """
+
+    if dctx.ctx.doc.user.treat_markdown_warnings_as_error
+        error(message)
+    else
+        @warn(message)
+    end
     return string(e.ref)
 end
 

src/latex/LaTeXWriter.jl

@@ -850,18 +850,21 @@ latex(io::Context, node::Node, ::Documenter.MetaNode) = _println(io, "\n")
 latex(io::Context, node::Node, ::Documenter.SetupNode) = nothing
 
 function latex(io::Context, node::Node, value::MarkdownAST.JuliaValue)
-    @warn(
-        """
-        Unexpected Julia interpolation in the Markdown. This probably means that you
-        have an unbalanced or un-escaped \$ in the text.
+    message = """
+    Unexpected Julia interpolation in the Markdown. This probably means that you have an unbalanced
+    or un-escaped \$ in the text.
 
-        To write the dollar sign, escape it with `\\\$`
+    To write the dollar sign, escape it with `\\\$`
 
-        We don't have the file or line number available, but we got given the value:
+    We don't have the file or line number available, but we got given the value:
 
-        `$(value.ref)` which is of type `$(typeof(value.ref))`
-        """
-    )
+    `$(value.ref)` which is of type `$(typeof(value.ref))`
+    """
+    if io.doc.user.treat_markdown_warnings_as_error
+        error(message)
+    else
+        @warn(message)
+    end
     return latexesc(io, string(value.ref))
 end
 

src/makedocs.jl

@@ -234,6 +234,9 @@ The only case where you may want to consider passing `true` is when you are auto
 deploying the documentation for a package release. In that case, `warnonly` should be set
 dynamically by checking the relevant environment variables set by the CI system.
 
+**`treat_markdown_warnings_as_error`** can be used to control whether a build fails with error, or
+simply prints a warning if it detects unintended julia values within the markdown.
+
 **`workdir`** determines the working directory where `@example` and `@repl` code blocks are
 executed. It can be either a path or the special value `:build` (default).