Give precedence to `html_root_url` over `--extern-html-root-url` by default, but add a way to opt-in to the previous behavior
## What is an HTML root url?
It tells rustdoc where it should link when documentation for a crate is
not available locally; for example, when a crate is a dependency of a
crate documented with `cargo doc --no-deps`.
## What is the difference between `html_root_url` and `--extern-html-root-url`?
Both of these tell rustdoc what the HTML root should be set to.
`doc(html_root_url)` is set by the crate author, while
`--extern-html-root-url` is set by the person documenting the crate.
These are often different. For example, docs.rs uses
`--extern-html-root-url https://docs.rs/crate-name/version` to ensure
all crates have documentation, even if `html_root_url` is not set.
Conversely, crates such as Rocket set `doc(html_root_url =
"https://api.rocket.rs")`, because they prefer users to view the
documentation on their own site.
Crates also set `html_root_url` to ensure they have
documentation when building locally when offline. This is unfortunate to
require, because it's more work from the library author. It also makes
it impossible to distinguish between crates that want to be viewed on a
different site (e.g. Rocket) and crates that just want documentation to
be visible offline at all (e.g. Tokio). I have authored a separate
change to the API guidelines to no longer recommend doing this:
rust-lang/api-guidelines#230.
## Why change the default?
In the past, docs.rs has been the main user of `--extern-html-root-url`.
However, it's useful for other projects as well. In particular, Cargo
wants to pass it by default when running `--no-deps`
(rust-lang/cargo#8296).
Unfortunately, for these other use cases, the priority order is
inverted. They want to give *precedence* to the URL the crate picks, and
only fall back to the `--extern-html-root` if no `html_root_url` is
present. That allows passing `--extern-html-root` unconditionally,
without having to parse the source code to see what attributes are
present.
For docs.rs, however, we still want to keep the old behavior, so that
all links on docs.rs stay on the site.
Refactor fallback code to prepare for never type
This PR contains cherry-picks of some of `@nikomatsakis's` work from #79366, and shouldn't (AFAICT) represent any change in behavior. However, the refactoring is good regardless of the never type work being landed, and will reduce the size of those eventual PR(s) (and rebase pain).
I am not personally an expert on this code, and the commits are essentially 100% `@nikomatsakis's,` but they do seem reasonable to me by my understanding. Happy to edit with review, of course. Commits are best reviewed in sequence rather than all together.
r? `@jackh726` perhaps?
[rustdoc] Wrap code blocks in <code> tag
This PR modifies Rustdoc output so that fenced code snippets, items and whole file source codes are wrapped in `<pre><code>` instead of just `<pre>`. This should improve the semantic meaning of the generated content.
I'm not sure what to do about `render_attributes_in_pre` and `render_attributes_in_code`. These functions were clearly expected to be used for things inside `<pre>` or `<code>`, and since I added `<code>` in this PR, some of them will be used in a different context than before. However, it seems to me that even before they were not consistent. For example, `item_constant` used `render_attributes_in_code` for its attributes, however there was no `<code>` used for constants before this PR...
Should I create some `rustdoc-gui` tests? For example to check that all `<pre>` tags have a `<code>` child?
Fixes: https://github.com/rust-lang/rust/issues/88020
## What is an HTML root url?
It tells rustdoc where it should link when documentation for a crate is
not available locally; for example, when a crate is a dependency of a
crate documented with `cargo doc --no-deps`.
## What is the difference between `html_root_url` and `--extern-html-root-url`?
Both of these tell rustdoc what the HTML root should be set to.
`doc(html_root_url)` is set by the crate author, while
`--extern-html-root-url` is set by the person documenting the crate.
These are often different. For example, docs.rs uses
`--extern-html-root-url https://docs.rs/crate-name/version` to ensure
all crates have documentation, even if `html_root_url` is not set.
Conversely, crates such as Rocket set `doc(html_root_url =
"https://api.rocket.rs")`, because they prefer users to view the
documentation on their own site.
Crates also set `html_root_url` to ensure they have
documentation when building locally when offline. This is unfortunate to
require, because it's more work from the library author. It also makes
it impossible to distinguish between crates that want to be viewed on a
different site (e.g. Rocket) and crates that just want documentation to
be visible offline at all (e.g. Tokio). I have authored a separate
change to the API guidelines to no longer recommend doing this:
https://github.com/rust-lang/api-guidelines/pull/230.
## Why change the default?
In the past, docs.rs has been the main user of `--extern-html-root-url`.
However, it's useful for other projects as well. In particular, Cargo
wants to pass it by default when running `--no-deps`
(https://github.com/rust-lang/cargo/issues/8296).
Unfortunately, for these other use cases, the priority order is
inverted. They want to give *precedence* to the URL the crate picks, and
only fall back to the `--extern-html-root` if no `html_root_url` is
present. That allows passing `--extern-html-root` unconditionally,
without having to parse the source code to see what attributes are
present.
For docs.rs, however, we still want to keep the old behavior, so that
all links on docs.rs stay on the site.
[rustdoc] Copy only item path to clipboard rather than full `use` statement.
The (somewhat) recent addition of the "copy item import to clipboard" button is extremely nice.
However, i tend to write my code with fully qualified paths wherever feasible and only resort to `use` statements as a refactoring pass. This makes the "copy to clipboard" workflow awkward to use, as i would be copy-pasting that as, say
```rust
impl use std::ops::Add; for MyType {
```
and then go back and remove the `use ` and `;`.
This PR removes the `use ;` decorations, making it much nicer to use for fully-qualified items. I argue, however, that this does not noticeably degrade experience for those who prefer to import items, since the hard part about those is getting the path right, and writing the `use ;` decoration can be done by hand with little effort.
Try filtering out non-const impls when we expect const impls
**TL;DR**: Associated types on const impls are now bounded; we now disallow calling a const function with bounds when the specified type param only has a non-const impl.
r? `@oli-obk`
Closes#87828
The issue seems to stem from #87210 where code headings were changed from a heading containing code to a heading with the `code-header` class. `rustdoc.css` was updated, but `ayu.css` was missed.
rustc: Replace `HirId`s with `LocalDefId`s in `AccessLevels` tables
and passes using those tables - primarily privacy checking, stability checking and dead code checking.
All these passes work with definitions rather than with arbitrary HIR nodes.
r? `@cjgillot`
cc `@lambinoo` (#87487)
This way, we can show the plus and minus buttons on screens, while voice
control will read off actual words "Collapse" and "Expand" instead of reading
"open brace minus close brace" and "open brace plus close brace".
Part of #87059
