Move rendering of examples into
Finalize design
Cleanup, rename found -> scraped
Softer yellow
Clean up dead code
Document scrape_examples
More simplification and documentation
Remove extra css
Test
This cleans up the other spot I found where rustdoc was rendering bounds
into the lifetime name itself. However, in this case, I don't think it
could have actually happened because higher-ranked lifetime definitions
aren't currently allowed to have bounds.
Refactor Markdown length-limited summary implementation
This PR is a new approach to #79749.
This PR refactors the implementation of `markdown_summary_with_limit()`,
separating the logic of determining when the limit has been reached from
the actual rendering process.
The main advantage of the new approach is that it guarantees that all
HTML tags are closed, whereas the previous implementation could generate
tags that were never closed. It also ensures that no empty tags are
generated (e.g., `<em></em>`).
The new implementation consists of a general-purpose struct
`HtmlWithLimit` that manages the length-limiting logic and a function
`markdown_summary_with_limit()` that renders Markdown to HTML using the
struct.
r? `@GuillaumeGomez`
This commit refactors the implementation of
`markdown_summary_with_limit()`, separating the logic of determining
when the limit has been reached from the actual rendering process.
The main advantage of the new approach is that it guarantees that all
HTML tags are closed, whereas the previous implementation could generate
tags that were never closed. It also ensures that no empty tags are
generated (e.g., `<em></em>`).
The new implementation consists of a general-purpose struct
`HtmlWithLimit` that manages the length-limiting logic and a function
`markdown_summary_with_limit()` that renders Markdown to HTML using the
struct.
## 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.
Because specifying these flags multiple times will never be discernibly different in functionality from specifying them a single time, there is no reason to fail and report an error to the user.
rustdoc: link to stable/beta docs consistently in documentation
This is an alternative to https://github.com/rust-lang/rust/pull/84941 which fixes the problem consistently by linking to stable/beta for *all* items, not just for primitives.
## User-facing changes
- Intra-doc links to primitives that currently go to rust-lang.org/nightly/std/primitive.x.html will start going to channel that rustdoc was built with. Nightly will continue going to /nightly; Beta will link to /beta; stable compilers will link to /1.52.1 (or whatever version they were built as).
- Cross-crate links from std to core currently go to /nightly unconditionally. They will start going to /1.52.0 on stable channels (but remain the same on nightly channels).
- Intra-crate links from std to std (or core to core) currently go to the same URL they are hosted at; they will continue to do so. Notably, this is different from everything else because it can preserve the distinction between /stable and /1.52.0 by using relative links.
Note that "links" includes both intra-doc links and rustdoc's own
automatically generated hyperlinks.
## Implementation changes
- Update the testsuite to allow linking to /beta and /1.52.1 in docs
- Use an html_root_url for the standard library that's dependent on the channel
This avoids linking to nightly docs on stable.
- Update rustdoc to use channel-dependent links for primitives from an
unknown crate
- Set DOC_RUST_LANG_ORG_CHANNEL from bootstrap to ensure it's in sync
- Include doc.rust-lang.org in the channel
cc Mark-Simulacrum - I know [you were dubious about this in the past](https://rust-lang.zulipchat.com/#narrow/stream/122651-general/topic/Rustdoc.20unconditionally.20links.20to.20nightly.20libstd.20docs/near/231223124), but I'm not quite sure why? I see this as "just a bugfix", I don't know why rustdoc should unconditionally link to nightly.
cc dtolnay who commented in https://github.com/rust-lang/rust/issues/30693:
> I would welcome a PR to solve this permanently if anyone has ideas for how. I don't believe we need an RFC.
Fixes https://github.com/rust-lang/rust/issues/30693 (note that issue is marked as feature-accepted, although I don't see where it was discussed).
## User-facing changes
- Intra-doc links to primitives that currently go to rust-lang.org/nightly/std/primitive.x.html will start going to channel that rustdoc was built with. Nightly will continue going to /nightly; Beta will link to /beta; stable compilers will link to /1.52.1 (or whatever version they were built as).
- Cross-crate links from std to core currently go to /nightly unconditionally. They will start going to /1.52.0 on stable channels (but remain the same on nightly channels).
- Intra-crate links from std to std (or core to core) currently go to the same URL they are hosted at; they will continue to do so. Notably, this is different from everything else because it can preserve the distinction between /stable and /1.52.0 by using relative links.
Note that "links" includes both intra-doc links and rustdoc's own
automatically generated hyperlinks.
## Implementation changes
- Update the testsuite to allow linking to /beta and /1.52.1 in docs
- Use an html_root_url for the standard library that's dependent on the channel
This avoids linking to nightly docs on stable.
- Update rustdoc to use channel-dependent links for primitives from an
unknown crate
- Set DOC_RUST_LANG_ORG_CHANNEL from bootstrap to ensure it's in sync
- Include doc.rust-lang.org in the channel
Support for force-warns
Implements https://github.com/rust-lang/rust/issues/85512.
This PR adds a new command line option `force-warns` which will force the provided lints to warn even if they are allowed by some other mechanism such as `#![allow(warnings)]`.
Some remaining issues:
* https://github.com/rust-lang/rust/issues/85512 mentions that `force-warns` should also be capable of taking lint groups instead of individual lints. This is not implemented.
* If a lint has a higher warning level than `warn`, this will cause that lint to warn instead. We probably want to allow the lint to error if it is set to a higher lint and is not allowed somewhere else.
* One test is currently ignored because it's not working - when a deny-by-default lint is allowed, it does not currently warn under `force-warns`. I'm not sure why, but I wanted to get this in before the weekend.
r? `@nikomatsakis`
That PR caused multiple test failures when Rust's channel is changed
from nightly to anything else. The commit will have to be landed again
after the test suite is fixed.
added --no-run option for rustdoc
resolve#59053
add `--no-run` option for `rustdoc` for compiling doc test but not running them.
Intended for use with `--persist-doctests`.
Don't rebuild rustdoc and clippy after checking bootstrap
This works by unconditionally passing -Z unstable-options to the
compiler. This has no affect in practice since bootstrap doesn't use
`deny(rustc::internal)`.
Fixes https://github.com/rust-lang/rust/issues/82461.
r? ```@Mark-Simulacrum```
Instead of using a depth counter and adding "../" to get to the top,
this commit makes rustdoc actually compare the path of what it's
linking from to the path that it's linking to. This makes the resulting
HTML shorter.
Here's a comparison of one of the largest (non-source) files in the
Rust standard library docs (about 4% improvement before gzipping).
$ wc -c struct.Wrapping.old.html struct.Wrapping.new.html
2387389 struct.Wrapping.old.html
2298538 struct.Wrapping.new.html
Most if it can be efficiently gzipped away.
$ wc -c struct.Wrapping.old.html.gz struct.Wrapping.new.html.gz
70679 struct.Wrapping.old.html.gz
70050 struct.Wrapping.new.html.gz
But it also makes a difference in the final DOM size, reducing it from 91MiB to 82MiB.
rustdoc: Don't load all extern crates unconditionally
Instead, only load the crates that are linked to with intra-doc links.
This doesn't help very much with any of rustdoc's fundamental issues
with freezing the resolver, but it at least fixes a stable-to-stable
regression, and makes the crate loading model somewhat more consistent
with rustc's. I tested and it unfortunately does not help at all with https://github.com/rust-lang/rust/pull/82496.
Closes https://github.com/rust-lang/rust/issues/68427. Let me know if you want me to open a separate issue for not freezing the resolver.
r? `@petrochenkov` cc `@eddyb` `@ollie27`
Instead, only load the crates that are linked to with intra-doc links.
This doesn't help very much with any of rustdoc's fundamental issues
with freezing the resolver, but it at least fixes a stable-to-stable
regression, and makes the crate loading model somewhat more consistent
with rustc's.
