Build docs into a different directory

[brson]

Putting our doc artifacts in the same directory as the source causes problems like in #11833, and it makes some problems for make clean when we do an in-tree build (I think we probably don't clean some of the docs because of this). Let's do the build into a different directory, maybe doc-build, or doc/build? Any better ideas?

[alexcrichton]

We use the CFG_BUILD version of rustdoc to generate docs, so could we build into $(CFG_BUILD)/doc ?

[huonw]

Could we enforce out-of-tree builds like servo does?

[brson]

@huonw We could, but servo only does it because the build system is so bad that an in-tree build causes havok. The docs are the only problem I'm aware of with ours.

[lilyball]

@alexcrichton Does the built docs actually depend on the host/target platform? If so, using CFG_BUILD actually makes sense. If not, then I think doc/build is better.

[alexcrichton]

How about moving the docs to src/docs?

[lilyball]

@alexcrichton I take it you mean put the documentation source in src/docs and leave the documentation output in doc? I like that.