Documentation for size_threshold?

[johnomotani]

When some HTML file is generated bigger than size_threshold I get an error message like

┌ Error: Generated HTML over size_threshold limit: zz_makie_post_processing.md
│     Generated file size: 368.98 (KiB)
│     size_threshold_warn: 100.0 (KiB)
│     size_threshold:      200.0 (KiB)
│     HTML file:           zz_makie_post_processing.html
└ @ Documenter.HTMLWriter ~/.julia/packages/Documenter/C1XEF/src/html/HTMLWriter.jl:1825

It is not obvious how I am supposed to fix this. I suppose the 'best' thing is supposed to be to rewrite the page so that it is smaller, but often probably I just want to change size_threshold either for one file or for the project. How do I do this? I could not find any relevant documentation in a ~10 minute search - the only mention I see is in the docstring for Documenter.HTMLWriter.HTML, but I don't ever call that explicitly so I don't know how to pass arguments to it. My best guess was to pass size_threshold as a kwarg to makedocs(), but it does not exist. So I think:

• The documentation should say how to set size_threshold somewhere
• The error message should suggest how to set size_threshold, or point to the documentation where it is explained

 
 
On a related note, but less important - it would be nice if the kwargs for makedocs() would auto-complete. I guess that would mean duplicating them from the Document() constructor, which is a bit of a pain, but would make for a significantly better user experience.
Also it might be clearer to list all the kwargs in the function signature of the makedocs() docstring, instead of using others...? It's not mentioned what others... is for in the docstring, and a reasonable guess would be that they are extra keyword arguments (for example size_threshold) that might be passed through to a specific backend. I think removing mention of others... from the docstring would make it clear that the specifically mentioned kwargs are the only ones.

[goerz]

I think it's a failure of the manual to start with "Building and Empty Document". Instead of some hypothetical "minimum working example", it should show a basic configuration that works for most new projects. That would include a setup like

makedocs(…,
    format = Documenter.HTML(
       …
    )
)

That is, your makedocs should include the call to Documenter.HTML, and that's where you set the option.

The docstring of makedocs itself also hides the (pretty essential) format options too much.