Docs.rs: stop building crates on all targets

[QuietMisdreavus]

After seeing the build queue get backed up by crates that take a long time to build (https://github.com/rust-lang/docs.rs/issues/335), i'm starting to wonder about the utility of building crates for all platforms all the time.

Currently, when we build a crate, we build it seven times:

• Once as the "initial" build, to prove that the crate builds in the first place. This generates the log shown in the builds page. If a crate specifies a default-target in its [package.metadata.docs.rs] it will use that target, otherwise it will build using the system's default of x86_64-unknown-linux-gnu.
• Six more times, to fill in all the supported targets:
  
  
  
  • i686-apple-darwin
  
  
  • i686-pc-windows-msvc
  
  
  • i686-unknown-linux-gnu
  
  
  • x86_64-apple-darwin
  
  
  • x86_64-pc-windows-msvc
  
  
  • x86_64-unknown-linux-gnu
  
  

This can cause a crate's build time to stretch out unnecessarily, especially if there are no API/docs differences between 32-/64-bit, or between Windows/Mac/Linux.

I'd like to propose removing the six extra builds, and replacing them with an additional-targets configuration item that would allow crates to choose which targets to build on. In the absence of this field, we would only build once for default-target (or x86_64-unknown-linux-gnu), and not create any additional builds.

This will allow us to build much more crates a lot faster, making it less likely that releasing a bunch of stm32 crates at the same time will clog up the queue again. On the other hand, crates would have to start listing the platforms they want to build with, instead of just depending on docs.rs to build the major platforms without asking.

[GuillaumeGomez]

I think this is a good idea. Alongside this, we should try to make docs.rs specific options (more) easily available. We're starting to have a few and it'd be a shame that people don't know about them!

[dekellum]

Like in section _Metadata for custom builds_ of https://docs.rs/about ?

Though it could use short descriptions of each item. In this context, I'm not personally sure what default-target does, for example.

[jamesmunns]

We (embedded-wg) would definitely love a conservative opt-in version of this to prevent our crates from being built for all non-embedded targets, as typically we only build for one or a few thumb* targets.

CC @adamgreig @killercup

[jyn514]

Now that #632 is merged, you should be able to opt-in to only building one target with

[package.metadata.docs.rs]
targets = [] # or targets = ["x86_64-unknown-linux-gnu"] if you think that looks nicer

See https://docs.rs/about#metadata for full documentation.