Support running rustdoc and displaying the rendered output

[Nemo157]

I (and many others) regularly use the playground as a quick way to provide small examples showing rustc/clippy error cases when filing bug reports. One thing I have run into a few times is wanting to do something similar when filing rustdoc bug reports (or providing examples on Discord/Discourse).

I haven't looked into the feasibility of this much, but one thought was that it should be possible to have a tiny single-page webapp that loads an archive built with https://github.com/killercup/static-filez and allows browsing with the links inside it. The playground would then just need to run rustdoc + static-filez on the snippet and load the resulting archive with the webapp in a new page.

[shepmaster]

Quick thoughts:

• running rustdoc isn't hard by itself, although we'd have to pre-build all the docs for the provided crates like we pre-compile them.
• displaying the rendered docs does seem harder. Cargo is run inside of a Docker container and the webservers are outside: the playground server is behind an Nginx proxy.
• Currently, files (such as assembly output) are read and immediately returned to the user. The question of persistence is a difficult concept — how long would the rendered documentation be available?

[Nemo157]

although we'd have to pre-build all the docs for the provided crates like we pre-compile them.

My expectation would be that it would be like cargo docs --no-deps, linking to the already hosted documentation for the dependencies elsewhere.

---

The display and persistence issues are why I thought of using something like static-filez to reduce the output down to one or two files. Then it may be possible to send those to the frontend over the same channels used for console/assembly output, they can be stored in-memory and a small static webapp that can understand and display them is loaded into a new window. At no point will the backend need to keep the files around to be loaded later.

[shepmaster]

linking to the already hosted documentation

I haven't actually used this; is there a way to get it to point to docs.rs?

send those to the frontend over the same channels

Ah, I see. Using something like static-filez (or maybe large pieces of it).

Certainly seems possible; I'd be happy to help someone prototype this.

[Nemo157]

is there a way to get it to point to docs.rs?

There's the --extern-html-root-url NAME=URL flag for rustdoc which I believe can be used to override the html_root_url set in each crate.

[jyn514]

FWIW I would be happy with just running rustdoc and not showing the rendered docs. That would be enough to show ICEs and most bugs.