set cfg(rustdoc) when rustdoc is running on a crate
When using `#[doc(cfg)]` to document platform-specific items, it's a little cumbersome to get all the platforms' items to appear all at once. For example, the standard library adds `--cfg dox` to rustdoc's command line whenever it builds docs, and the documentation for `#![feature(doc_cfg)]` suggests using a Cargo feature to approximate the same thing. This is a little awkward, because you always need to remember to set `--features dox` whenever you build documentation.
This PR proposes making rustdoc set `#[cfg(rustdoc)]` whenever it runs on a crate, to provide an officially-sanctioned version of this that is set automatically. This way, there's a standardized way to declare that a certain version of an item is specifically when building docs.
To try to prevent the spread of this feature from happening too quickly, this PR also restricts the use of this flag to whenever `#![feature(doc_cfg)]` is active. I'm sure there are other uses for this, but right now i'm tying it to this feature. (If it makes more sense to give this its own feature, i can easily do that.)
rustdoc: add flag to control the html_root_url of dependencies
The `--extern-html-root-url` flag in this PR allows one to override links to crates whose docs are not already available locally in the doc bundle. Docs.rs currently uses a version of this to make sure links to other crates go into that crate's docs.rs page. See the included test for intended use, but the idea is as follows:
Calling rustdoc with `--extern-html-root-url crate=https://some-url.com` will cause rustdoc to override links that point to that crate to instead be replaced with a link rooted at `https://some-url.com/`. (e.g. for docs.rs this would be `https://docs.rs/crate/0.1.0` or the like.) Cheekily, rustup could use these options to redirect links to std/core/etc to instead point to locally-downloaded docs, if it so desired.
Fixes https://github.com/rust-lang/rust/issues/19603
Mention spec and indented blocks in doctest docs
Fixes#49717.
This commit adds a new section to the Documentation Test docs, which briefly mentions indented code blocks, and links to the CommonMark specification for both.
I’m not sure about saying "fenced code blocks the more popular choice in the Rust community” because it seems like I’m speaking for everyone, but I can’t think of a better way to phrase it!
Update rustdoc book to suggest using Termination trait instead of hidden ‘foo’ function
Closes#50721.
I suggest that someone double-checks my English since I am not a native speaker.
r? @steveklabnik
Add doc comment to hiding portions of code example
fixes#50816
Not sure if this is all that's needed, but I think it's a good start. One thing to note is that the code block is a text block where it could possibly be a rust block.
This commit adds a new section to the Documentation Test docs, which briefly mentions indented code blocks, and links to the CommonMark specification for both.
I’m not sure about saying "fenced code blocks the more popular choice in the Rust community” because it seems like I’m speaking for everyone, but I can’t think of a better way to phrase it!
The example code snippets for the `no_run` and `compile_fail` attributes
in the rustdoc documentation were followed by the description for the
wrong attribute. This patch reorders the descriptions to match the code
snippets.
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.
