Add size_threshold_ignore to HTML (#2252)

CHANGELOG.md

@@ -48,11 +48,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   **For upgrading:** You should double check and fix all the offending links. Alternatively, you can also set `strict = Documenter.except(:cross_references)`, so that the errors would be reduced to warnings (however, this is not recommended, as you will have broken links in your generated documentation).
 
-* The HTML output now enforces size thresholds for the generated HTML files, to catch cases where Documenter is deploying extremely large HTML files (usually due to generated content, like figures).
-  If any generated HTML file is above either of the thresholds, Documenter will either error and fail the build (if above `size_threshold`), or warn (if above `size_threshold_warn`). ([#2142], [#2205])
+* The HTML output now enforces size thresholds for the generated HTML files, to catch cases where Documenter is deploying extremely large HTML files (usually due to generated content, like figures). If any generated HTML file is above either of the thresholds, Documenter will either error and fail the build (if above `size_threshold`), or warn (if above `size_threshold_warn`). The size threshold can also be ignored for specific pages with `size_threshold_ignore`. ([#2142], [#2205], [#2211], [#2252])
 
   **For upgrading:** If your builds are now failing due to the size threshold checks, you should first investigate why the generated HTML files are so large (e.g. you are likely automatically generating too much HTML, like extremely large inline SVG figures), and try to reduce them below the default thresholds.
   If you are unable to reduce the generated file size, you can increase the `size_threshold` value to just above the maximum size, or disable the enforcement of size threshold checks altogether by setting `size_threshold = nothing`.
+  If it is just a few specific pages that are offending, you can also ignore those with `size_threshold_ignore`.
 
 * User-provided `assets/search.js` files no longer override Documenter's default search implementation, and the user-provided now gets ignored by default. ([#2236])
 
@@ -1643,11 +1643,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2194]: https://github.com/JuliaDocs/Documenter.jl/issues/2194
 [#2202]: https://github.com/JuliaDocs/Documenter.jl/issues/2202
 [#2205]: https://github.com/JuliaDocs/Documenter.jl/issues/2205
+[#2211]: https://github.com/JuliaDocs/Documenter.jl/issues/2211
 [#2213]: https://github.com/JuliaDocs/Documenter.jl/issues/2213
 [#2214]: https://github.com/JuliaDocs/Documenter.jl/issues/2214
 [#2215]: https://github.com/JuliaDocs/Documenter.jl/issues/2215
 [#2216]: https://github.com/JuliaDocs/Documenter.jl/issues/2216
 [#2236]: https://github.com/JuliaDocs/Documenter.jl/issues/2236
+[#2252]: https://github.com/JuliaDocs/Documenter.jl/issues/2252
 [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/html/HTMLWriter.jl

@@ -369,6 +369,11 @@ increases of this default value will be considered to be non-breaking).
 print a warning, instead of throwing an error. Defaults to `100 KiB`, and must be less than or equal to
 `size_threshold`.
 
+**`size_threshold_ignore`** can be passed a list of pages for which the size thresholds are completely
+ignored (silently). The arguments should be the same file paths as for the `pages` argument of
+[`makedocs`](@ref Documenter.makedocs). Using this argument to ignore a few specific pages is preferred
+over setting a high general limit, or disabling the size checking altogether.
+
 !!! note "Purpose of HTML size thresholds"
 
     The size threshold, with a reasonable default, exists so that users would not deploy huge pages
@@ -444,6 +449,7 @@ struct HTML <: Documenter.Writer
     highlightjs   :: Union{String,Nothing}
     size_threshold :: Int
     size_threshold_warn :: Int
+    size_threshold_ignore :: Vector{String}
 
     function HTML(;
             prettyurls    :: Bool = true,
@@ -467,6 +473,7 @@ struct HTML <: Documenter.Writer
             highlightjs   :: Union{String,Nothing} = nothing,
             size_threshold :: Union{Integer, Nothing} = 200 * 2^10,
             size_threshold_warn :: Union{Integer, Nothing} = 100 * 2^10,
+            size_threshold_ignore :: Vector = String[],
 
             # deprecated keywords
             edit_branch   :: Union{String, Nothing, Default} = Default(nothing),
@@ -516,7 +523,7 @@ struct HTML <: Documenter.Writer
         new(prettyurls, disable_git, edit_link, repolink, canonical, assets, analytics,
             collapselevel, sidebar_sitename, highlights, mathengine, description, footer,
             ansicolor, lang, warn_outdated, prerender, node, highlightjs,
-            size_threshold, size_threshold_warn,
+            size_threshold, size_threshold_warn, size_threshold_ignore,
         )
     end
 end
@@ -1712,7 +1719,14 @@ function write_html(ctx::HTMLContext, navnode::Documenter.NavNode, page_html::DO
         Generated file size: $(file_size) (bytes)
         size_threshold_warn: $(ctx.settings.size_threshold_warn) (bytes)
         size_threshold:      $(ctx.settings.size_threshold) (bytes)"""
-    if file_size > ctx.settings.size_threshold
+    if navnode.page in ctx.settings.size_threshold_ignore
+        if file_size > ctx.settings.size_threshold_warn
+            @debug """
+            $(size_threshold_msg(:size_threshold_warn))
+            Hard limit ignored due to 'size_threshold_ignore'.
+            """ size_threshold_ignore = ctx.settings.size_threshold_ignore
+        end
+    elseif file_size > ctx.settings.size_threshold
         @error size_threshold_msg(:size_threshold)
         return false
     elseif file_size > ctx.settings.size_threshold_warn

test/examples/make.jl

@@ -18,7 +18,7 @@ EXAMPLE_BUILDS = if haskey(ENV, "DOCUMENTER_TEST_EXAMPLES")
 else
     ["html", "html-meta-custom", "html-mathjax2-custom", "html-mathjax3", "html-mathjax3-custom",
     "html-local", "html-draft", "html-repo-git", "html-repo-nothing", "html-repo-error",
-    "html-sizethreshold-defaults-fail", "html-sizethreshold-success", "html-sizethreshold-ignore-success", "html-sizethreshold-override-fail",
+    "html-sizethreshold-defaults-fail", "html-sizethreshold-success", "html-sizethreshold-ignore-success", "html-sizethreshold-override-fail", "html-sizethreshold-ignore-success", "html-sizethreshold-ignore-fail",
     "latex_texonly", "latex_simple_texonly", "latex_showcase_texonly", "html-pagesonly"]
 end
 
@@ -532,6 +532,35 @@ end
         e
     end
 end
+@examplebuild "sizethreshold-ignore-success" begin
+    @quietly try
+        makedocs(;
+            sitename = "Megabyte",
+            root  = examples_root,
+            build = "builds/sizethreshold-defaults-fail",
+            source = "src.megapage",
+            format = Documenter.HTML(size_threshold_ignore = ["index.md"]),
+            debug = true,
+        )
+    catch e
+        e
+    end
+end
+@examplebuild "sizethreshold-ignore-fail" begin
+    @quietly try
+        makedocs(;
+            sitename = "Megabyte",
+            root  = examples_root,
+            build = "builds/sizethreshold-defaults-fail",
+            source = "src.megapage",
+            # Note: it's fine to pass non-existent pages to size_threshold_ignore
+            format = Documenter.HTML(size_threshold_ignore = ["foo.md"]),
+            debug = true,
+        )
+    catch e
+        e
+    end
+end
 
 # PDF/LaTeX
 examples_latex_simple_doc = if "latex_simple" in EXAMPLE_BUILDS

test/examples/tests.jl

@@ -250,6 +250,8 @@ end
         @test examples_html_sizethreshold_success_doc isa Documenter.Document
         @test examples_html_sizethreshold_ignore_success_doc isa Documenter.Document
         @test examples_html_sizethreshold_override_fail_doc isa Documenter.HTMLWriter.HTMLSizeThresholdError
+        @test examples_html_sizethreshold_ignore_success_doc isa Documenter.Document
+        @test examples_html_sizethreshold_ignore_fail_doc isa Documenter.HTMLWriter.HTMLSizeThresholdError
     end
 
     @testset "PDF/LaTeX: TeX only" begin