Description
rustdoc was built under a single-crate-universe assumption: that the documentation would be just for that crate. While that assumption held, Rust-to-HTML generation worked fine.
This assumption is now broken. We have the implementors/**/*.js technique for trait implementatons; search pulls its information for many crates from one; the order in which you build the documentation of crates matters and—for the Rust repository—make docs produces different output to make -j docs.
It is precept upon precept,
precept upon precept;
line upon line,
line upon line;
here a little,
there a little.
It’s time to stop writing new workarounds and address the basic problem that we have here: rustdoc needs to handle this multiple-crates world intelligently. This means ditching the simple and, alas, simplistic single-pass Rust-to-HTML approach.
I propose in its stead this model:
- First pass, done per crate: extract all the metadata and write it in serialized form, not HTML/JavaScript/whatever. I don’t care what format.
- Second pass, which need only be done after all crates but can be done more frequently without harm: using the metadata, write all the HTML and whatever JavaScript is still necessary (this way, I think it will be for the search only, not the crate-level sidebar and trait implementations stuff).
By default, the second pass should probably still be run, but it can be turned off with a flag like --no-html for efficiency when you do have multiple crates. Or you can run the HTML pass by itself, which will allow meaningful Makefile dependencies in this blasé-with-respect-to-detail example, allowing efficient, consistent and correct make -j behaviour:
doc/index.html: doc/a.json doc/b.json doc/c.json
rustdoc --html doc/{a,b,c}.json
doc/%.json: src/%/lib.rs
rustdoc --no-html src/%/lib.rs