rustdoc: port the -C option from rustc
Blocked on https://github.com/rust-lang/rust/pull/49864. The included test won't work without those changes, so this PR includes those commits as well.
When documenting items that require certain target features, it helps to be able to force those target features into existence. Rather than include a flag just to parse those features, i instead decided to port the `-C` flag from rustc in its entirety. It takes the same parameters, because it runs through the same parsing function. This has the added benefit of being able to control the codegen of doctests as well.
One concern i have with the flag is that i set it to stable here. My rationale is that it is a direct port of functionality on rustc that is currently stable, used only in mechanisms that it is originally used for. If needed, i can set it back to be unstable.
Re-write the documentation index
The docs team has decided that we're framing resources in three ways:
"learning Rust," "using Rust," "mastering Rust." This is a more useful
split than "beginner/intermediate/advanced." As we add more resources
in the future, we expect "using Rust" to grow. "the bookshelf" as a
concept is great, but isn't really organized along these lines. As such,
this reorganizes the docs along these lines.
The docs team has decided that we're framing resources in three ways:
"learning Rust," "using Rust," "mastering Rust." This is a more useful
split than "beginner/intermediate/advanced." As we add more resources
in the future, we expect "using Rust" to grow. "the bookshelf" as a
concept is great, but isn't really organized along these lines. As such,
this reorganizes the docs along these lines.
rustdoc: add an --edition flag to compile docs/doctests with a certain edition
To correspond with the 2018 edition, this adds a (currently unstable) `--edition` flag to rustdoc that makes it compile crates and doctests with the given edition. Once this lands, Cargo should be updated to pass this flag when the edition configuration option is given.
add an "unstable features" chapter to the rustdoc book
There are several rustdoc features that currently are undocumented, but also don't fit with the rest of the Rustdoc Book since they're also unstable. Some of these have corresponding feature gates and chapters in the Unstable Book, but many don't, and i wanted a place to talk about them officially.
Goal: talk about everything rustdoc can do that needs nightly
- [x] Feature gates (extensions to the doc attribute that can be caught by the compiler)
- [x] doc(cfg)
- [x] doc(masked)
- [x] doc(spotlight)
- [x] doc(include)
- [x] Command-line flags (features that require a CLI flag to use, where the flag itself is a `-Z` command or otherwise requires `-Z unstable-options` before rustdoc will accept it)
- [x] markdown-before-content/markdown-after-content
- [x] playground-url
- [x] display-warnings
- [x] crate-version
- [x] linker
- [x] sort-modules-by-appearance
- [x] themes/theme-checker
- [x] resource-suffix
- [x] `-Z force-unstable-if-unmarked`
- [x] Nightly-gated functionality (features that are gated by requiring a nightly build without needing a CLI flag or a feature gate to unlock)
- [x] intra-links
- [x] error numbers for `compile_fail` doctests
Rustdoc: example of use of assertions
I added this section at the beginning of the file because it seems to be basic information. Let me know if there's someplace more relevant.
See #47945.
