Warn or error if generated HTML page is too large

[mortenpi]

We include the text/html output of plots etc directly in the generate HTML pages, which means it's quite easy to end up with HTML files that are tens of MBs (or more), if you e.g. have a plot with too many points.

We should at least print a warning if the file size goes above some reasonable (and configurable) limit. But it might even be a good idea to make this an error by default (in which case we'd want this in 1.0.0).

Not sure what a reasonable default limit would be. One option would be to do a quick survey of existing doc deployments.

cc @bauglir

[bauglir]

We should at least print a warning if the file size goes above some reasonable (and configurable) limit. But it might even be a good idea to make this an error by default (in which case we'd want this in 1.0.0).

A warning sounds like a good place to start. Although those might also easily get buried between other warnings when building documentation. At least some of the documentation builds that I see spit out very large amounts of logs. So an error might be better, especially in CI. This might be a bit of a nuisance for long builds if such an error completely fails the entire build, so perhaps this is more of a check at the end of a build? Or at least one that doesn't error until the end, so that build artifacts are available for inspection.

I'm not sure if you'd want to be able to explicitly turn this "off", or whether that'd just amount to setting a very high limit.

One option would be to do a quick survey of existing doc deployments.

The primary trigger for us to run into this was SEO. This is obviously a much bigger topic, but this (hopefully) might be something that is relatively easy to catch. I'm seeing some statements that the actual page size is not actually a factor here. This indicates that the large file sizes I'm seeing are only indicators of the actual issue which appears to be the ratio between "user readable content" and "HTML content", which I interpret as effectively element.innerText.length / element.innerHTML.length.

For what it's worth, speaking about absolute file sizes I start getting warnings for files just over 2MB in size. But if we're able to do the other comparison that might actually be more worthwhile.

For the ratio I actually have no idea what the exact limit should be. A quick search didn't surface any hard numbers. For the particular cases that I'm looking at we're talking about ratios of content to HTML of less than 1%.

[Dattax]

Hi @mortenpi - when you're back - what can we do to close out this issue? A warning is nice, but doesn't solve the actual problem...we can def ask the SEO specialists about this one if needed.