rustdoc: please provide way to filter out out-of-document included resources

[ijackson]

I run cargo doc quite a lot because I like to have documents locally. This means I can work without an internet connection; it means docs load very quickly; it means they are the versions I have selected; and it provides better privacy because it means no-one outside my systems is seeing which docs I load when.

However, there is a fly in this ointment: the docs sometimes contain offsite links. For example, my copy of the top-level page for rocket contains these:

<link rel="shortcut icon" href="https://rocket.rs/v0.4/images/favicon.ico">
<img src='https://rocket.rs/v0.4/images/logo-boxed.png' alt='logo'>

The top-level of rocket_cors contains these:

<img src="https://travis-ci.org/lawliet89/rocket_cors.svg" alt="Build Status" />
<img src="https://img.shields.io/github/tag/lawliet89/rocket_cors.svg" alt="Repository" />
<img src="https://img.shields.io/crates/v/rocket_cors.svg" alt="Crates.io" />

These are just two examples and I don't mean to criticise these crates. I don't think it would be sensible to try to solve my issue by asking every crate to refrain from using these kind of badges. (Although rocket's favicon and logo could surely be in the crate itself.)

The consequences are: if I don't have an internet connection, these docs don't load properly. (They load eventually but only after an http timeout.) If I do have an internet connection, these references tell shields.io and travis what I am doing, and I would prefer to avoid that.

I think instead that it would be best for there to be a way to ask rustdoc to eliminate all offsite resource inclusions in the generated outputs. This would probably best be done at late in the output stage, so that it is comprehensive.

As a stretch goal it would be nice for offsite links to be marked somehow. Thanks for your attention.

[jsha]

Hi! Thanks for the feature request and sorry it has sat here for so long. I think there are two main categories here:

• favicons / logos. Rustdoc has attributes that encourage this pattern, because they only support external URLs: [rustdoc, request] Please bundle local relative resources (favicon, logo, whatever) #79254. We should fix that, and that will nudge people towards including local files instead.

• badges / shields inserted by the doc author. We can't really prevent these. Markdown is defined to allow arbitrary HTML, which includes images. We could do a post-processing pass with some sort of HTML sanitizer but I think this is overly restrictive. As a minor mitigation you could use a browser extension to block some of the common domains, like shields.io and travis-ci.org.

Also, I'm surprised to hear that your browser blocks rendering of the page on these resources. For the logo provided by rustdoc, it should be explicitly sized, so it doesn't block layout. Maybe the badges / shields are blocking layout because they don't have explicit size? That's something where you could request a fix from the crate authors.

[ijackson]

Hi. Thanks for your attention.

We could do a post-processing pass with some sort of HTML sanitizer but I think this is overly restrictive.

I think this is what I am asking for; or, if it can't be done in rustdoc itself, a hook I can use to run an external postprocessor. I don't expect it to be turned on by default.

I don't agree that it's overly restrictive. From a privacy point of view, it should be possible to generate documentation that doesn't "phone home" to various places. That should work for all external resources, since as a privacy protection it ought not to have loopholes.

I appreciate that the notion of not wanting to be constantly tracked is unfashionable, but I think it is an important ambition that Rust ought to be able to for those that care about it.

I also don't think browser-based blocking is a sufficient approach. Consider for example, a distro like Debian, who want to ship inert documentation to their users.

Also, I'm surprised to hear that your browser blocks rendering of the page on these resources

I'm not sure that the problem is precisely that the rendering is blocked. I think part of it may be that the Javascript isn't arriving and being processed early enough. I haven't debugged this in detail, since I think the external connections are undesirable.

Possibly the number of included resources sometimes reaches my browser's external connections limit. (And I use a local web proxy so perhaps connections to all sites count towards the limit.)