Consider recommending cargo +nightly docs-rs --open for local documentation builds

[dtolnay]

Note

Full disclosure: I wrote this crate. https://github.com/dtolnay/cargo-docs-rs

I noticed this in the contribution guide:

tokio/CONTRIBUTING.md

Lines 155 to 169 in 01ed7b5

	When building documentation normally, the markers that list the features
	required for various parts of Tokio are missing. To build the documentation
	correctly, use this command:
	```
	RUSTDOCFLAGS="--cfg docsrs" RUSTFLAGS="--cfg docsrs" cargo +nightly doc --all-features
	```
	To build documentation including Tokio's unstable features, it is necessary to
	pass `--cfg tokio_unstable` to both RustDoc *and* rustc. To build the
	documentation for unstable features, use this command:
	```
	RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg docsrs --cfg tokio_unstable" cargo +nightly doc --all-features
	```

For my own projects, iterating on docs locally and also checking the documentation build in CI, I have a cargo docs-rs subcommand that loads the "package.metadata.docs.rs" section of Cargo.toml, and then delegates to a cargo rustdoc command with all those options applied in the same way that docs.rs's builds.

tokio/tokio/Cargo.toml

Lines 157 to 163 in 01ed7b5

	[package.metadata.docs.rs]
	all-features = true
	# enable unstable features in the documentation
	rustdoc-args = ["--cfg", "docsrs", "--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]
	# it's necessary to _also_ pass `--cfg tokio_unstable` and `--cfg tokio_taskdump`
	# to rustc, or else dependencies will not be enabled, and the docs build will fail.
	rustc-args = ["--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]

The output of cargo docs-rs --verbose shows what this turns into:

$ cargo docs-rs --verbose
     Running `cargo rustdoc -Zunstable-options -Zrustdoc-map -Zhost-config -Ztarget-applies-to-host
            --lib --all-features --target=x86_64-unknown-linux-gnu
            --config='build.rustflags=["--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]'
            --config='host.rustflags=["--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]'
            --config='build.rustdocflags=["-Zunstable-options", "--cfg=docsrs", "--cfg", "docsrs", "--cfg", "tokio_unstable", "--cfg", "tokio_taskdump", "--extern-html-root-takes-precedence"]'
            --config='doc.extern-map.registries.crates-io="https://docs.rs"'
            --verbose`

This matches the rustdoc command in tokio's docs.rs build log https://docs.rs/crate/tokio/1.37.0/builds/1172427 aside from some docs.rs-specific details (--emit=invocation-specific, --resource-suffix, --static-root-path, -j6).

[Darksonn]

Seems reasonable enough to me. I would still want the existing command in the documentation for people who don't want to install the tool, but making this the first recommendation sounds good to me.

We currently have two commands in the docs: one with and one without unstable features. But we should probably drop the one without unstable features since it isn't how docsrs will build it, and it emits warnings about broken links.

Do you want to submit a PR?

[dtolnay]

Sure thing: #6475. Thanks!