rustdoc: Consolidate static-file replacement mechanism
There were a few places in rustdoc where we would take static JS or CSS and rewrite it at doc generation time to insert values. This consolidates all the CSS instances into one CSS file and replaces the JS examples with data- attributes on the rustdoc-vars div.
Demo https://rustdoc.crud.net/jsha/static-file-replace/test_docs/
r? ``@GuillaumeGomez``
This can be replicated in full with other existing features, there's no
need to have a separate option for it.
This also fixes a bug where `--test-args=--show-output` had no effect,
and updates the documentation.
We carry around a list of stylesheets that can carry two different types
of thing:
1. Internal stylesheets specific to a page type (only for settings)
2. Themes
In this change I move the link generation for settings.css into
settings(), so Context.style_files is reserved just for themes.
We had two places where we extracted a base theme name from a list of
StylePaths. I consolidated that code to be a method on StylePath.
I moved generation of link tags for stylesheets into the page.html
template. With that change, I made the template responsible for special
handling of light.css (making it the default theme) and of the other
themes (marking them disabled). That allowed getting rid of the
`disabled` field on StylePath.
* Move call location logic from function constructor to rendering
* Fix issue with macro spans in scraping examples
* Clean up example loading logic
Documentation / newtype for DecorationInfo
Fix line number display
Serialize edition of call site, other small cleanup
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
## 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.
In #86157cd0f93193c
Use Tera templates for rustdoc.
dropped the following transformation from the keys of the default
settings element's `data-` attribute names:
.map(|(k, v)| format!(r#" data-{}="{}""#, k.replace('-', "_"), Escape(v)))
The `Escape` part is indeed no longer needed, because Tera does that
for us. But the massaging of `-` to `_` is needed, for the (bizarre)
reasons explained in the new comments.
I have tested that the default theme function works again for me. I
have also verified that passing
--default-theme="zork&"
escapes the value in the HTML.
Closes#87263.
CC: Jacob Hoffman-Andrews <github@hoffman-andrews.com>
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
Make `--force-warns` a normal lint level option
Now that `ForceWarn` is a lint level, there's no reason `--force-warns` should be treated differently from other options that set lint levels. This merges the `ForceWarn` handling in with the other lint level command line options. It also unifies all of the relevant selection logic in `compiler/rustc_lint/src/levels.rs`, rather than having some of it weirdly elsewhere.
Fixes#86958, which arose from the special-cased handling of `ForceWarn` having had an error in it.
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`
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`.
Fix handling of `--output-format json` flag
- Don't treat it as deprecated on stable and beta channels. Before, it
would give confusing and incorrect output:
```
warning: the 'output-format' flag is considered deprecated
|
= warning: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
error: json output format isn't supported for doc generation
```
Both of those are wrong: output-format isn't deprecated, and json
output is supported.
- Require -Z unstable-options for `--output-format json`
Previously, it was allowed by default on nightly, which made it hard
to realize the flag wouldn't be accepted on beta or stable.
To get the test working I had to remove `-Z unstable-options`, which x.py passed to compiletest unconditionally. It was first added in 8c2ec689c1 so `-Z miri` would be allowed. -Z miri is no longer passed unconditionally, so hopefully removing it won't break anything.
r? ```@aDotInTheVoid``` cc ```@HeroicKatora``` ```@CraftSpider```
Thanks to ```@memoryruins``` for pointing it out on Discord!
cc ```@Mark-Simulacrum``` for the change to compiletest.
- Don't treat it as deprecated on stable and beta channels. Before, it
would give confusing and incorrect output:
```
warning: the 'output-format' flag is considered deprecated
|
= warning: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
error: json output format isn't supported for doc generation
```
Both of those are wrong: output-format isn't deprecated, and json
output is supported.
- Require -Z unstable-options for `--output-format json`
Previously, it was allowed by default on nightly, which made it hard
to realize the flag wouldn't be accepted on beta or stable.
Note that this still allows `--output-format html`, which has been
stable since 1.0.
- Remove unnecessary double-checking of the feature gate when parsing
the output format
- Add custom run-make test since compiletest passes -Zunstable-options
by default
Give a better error when --theme is not a CSS file
Before:
```
error: invalid argument: "bacon.toml"
```
After:
```
error: invalid argument: "bacon.toml"
|
= help: arguments to --theme must be CSS files
```
cc https://github.com/rust-lang/rust/pull/83478
Remove unneeded INITIAL_IDS const
Some IDs inside this map didn't exist anymore, some others were duplicates of what we have inside `IdMap`. So instead of keeping the two around and since `INITIAL_IDS` was only used by `IdMap`, no need to keep both of them.
Add an unstable --json=unused-externs flag to print unused externs
This adds an unstable flag to print a list of the extern names not used by cargo.
This PR will enable cargo to collect unused dependencies from all units and provide warnings.
The companion PR to cargo is: https://github.com/rust-lang/cargo/pull/8437
The goal is eventual stabilization of this flag in rustc as well as in cargo.
Discussion of this feature is mostly contained inside these threads: #57274#72342#72603
The feature builds upon the internal datastructures added by #72342
Externs are uniquely identified by name and the information is sufficient for cargo.
If the mode is enabled, rustc will print json messages like:
```
{"unused_extern_names":["byteorder","openssl","webpki"]}
```
For a crate that got passed byteorder, openssl and webpki dependencies but needed none of them.
### Q: Why not pass -Wunused-crate-dependencies?
A: See [ehuss's comment here](https://github.com/rust-lang/rust/issues/57274#issuecomment-624839355)
TLDR: it's cleaner. Rust's warning system wasn't built to be filtered or edited by cargo.
Even a basic implementation of the feature would have to change the "n warnings emitted" line that rustc prints at the end.
Cargo ideally wants to synthesize its own warnings anyways. For example, it would be hard for rustc to emit warnings like
"dependency foo is only used by dev targets", suggesting to make it a dev-dependency instead.
### Q: Make rustc emit used or unused externs?
A: Emitting used externs has the advantage that it simplifies cargo's collection job.
However, emitting unused externs creates less data to be communicated between rustc and cargo.
Often you want to paste a cargo command obtained from `cargo build -vv` for doing something
completely unrelated. The message is emitted always, even if no warning or error is emitted.
At that point, even this tiny difference in "noise" matters. That's why I went with emitting unused externs.
### Q: One json msg per extern or a collective json msg?
A: Same as above, the data format should be concise. Having 30 lines for the 30 crates a crate uses would be disturbing to readers.
Also it helps the cargo implementation to know that there aren't more unused deps coming.
### Q: Why use names of externs instead of e.g. paths?
A: Names are both sufficient as well as neccessary to uniquely identify a passed `--extern` arg.
Names are sufficient because you *must* pass a name when passing an `--extern` arg.
Passing a path is optional on the other hand so rustc might also figure out a crate's location from the file system.
You can also put multiple paths for the same extern name, via e.g. `--extern hello=/usr/lib/hello.rmeta --extern hello=/usr/local/lib/hello.rmeta`,
but rustc will only ever use one of those paths.
Also, paths don't identify a dependency uniquely as it is possible to have multiple different extern names point to the same path.
So paths are ill-suited for identification.
### Q: What about 2015 edition crates?
A: They are fully supported.
Even on the 2015 edition, an explicit `--extern` flag is is required to enable `extern crate foo;` to work (outside of sysroot crates, which this flag doesn't warn about anyways).
So the lint would still fire on 2015 edition crates if you haven't included a dependency specified in Cargo.toml using `extern crate foo;` or similar.
The lint won't fire if your sole use in the crate is through a `extern crate foo;` statement, but that's not its job.
For detecting unused `extern crate foo` statements, there is the `unused_extern_crates` lint
which can be enabled by `#![warn(unused_extern_crates)]` or similar.
cc ```@jsgf``` ```@ehuss``` ```@petrochenkov``` ```@estebank```
rustdoc: Add an unstable option to print all unversioned files
This allows sharing those files between different doc invocations
without having to know their names ahead of time.
Helps with https://github.com/rust-lang/docs.rs/issues/1302.
r? ````@GuillaumeGomez```` cc ````@pietroalbini```` ````@Nemo157````
Cleanup rustdoc warnings
## Clean up error reporting for deprecated passes
Using `error!` here goes all the way back to the original commit, https://github.com/rust-lang/rust/pull/8540. I don't see any reason to use logging; rustdoc should use diagnostics wherever possible. See https://github.com/rust-lang/rust/pull/81932#issuecomment-785291244 for further context.
- Use spans for deprecated attributes
- Use a proper diagnostic for unknown passes, instead of error logging
- Add tests for unknown passes
- Improve some wording in diagnostics
## Report that `doc(plugins)` doesn't work using diagnostics instead of `eprintln!`
This also adds a test for the output.
This was added in https://github.com/rust-lang/rust/pull/52194. I don't see any particular reason not to use diagnostics here, I think it was just missed in https://github.com/rust-lang/rust/pull/50541.
