Commits on Aug 19, 2021

1. Give precedence to html_root_url over --extern-html-root-url by d… …

   …efault, 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.

   

   jyn514 committed Aug 19, 2021
   Configuration menu

   • View commit details
   • Copy full SHA for 18f0f24
   • Browse repository at this point

   Copy the full SHA

   18f0f24 View commit details

   Browse the repository at this point in the history