Revert "Remove html_root_url guideline"

This reverts commit 5c457df.

Author: dtolnay

src/checklist.md

@@ -36,6 +36,7 @@
   - [ ] Cargo.toml includes all common metadata ([C-METADATA])
     - authors, description, license, homepage, documentation, repository,
       readme, keywords, categories
+  - [ ] Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" ([C-HTML-ROOT])
   - [ ] Release notes document all significant changes ([C-RELNOTES])
   - [ ] Rustdoc does not show unhelpful implementation details ([C-HIDDEN])
 - **Predictability** *(crate enables legible code that acts how it looks)*
@@ -102,6 +103,7 @@
 [C-FAILURE]: documentation.html#c-failure
 [C-LINK]: documentation.html#c-link
 [C-METADATA]: documentation.html#c-metadata
+[C-HTML-ROOT]: documentation.html#c-html-root
 [C-RELNOTES]: documentation.html#c-relnotes
 [C-HIDDEN]: documentation.html#c-hidden
 

src/documentation.md

@@ -206,6 +206,38 @@ crate other than the source repository or API documentation. Do not make
 `homepage` redundant with either the `documentation` or `repository` values. For
 example, serde sets `homepage` to *https://serde.rs*, a dedicated website.
 
+[C-HTML-ROOT]: #c-html-root
+<a id="c-html-root"></a>
+### Crate sets html_root_url attribute (C-HTML-ROOT)
+
+It should point to `"https://docs.rs/CRATE/MAJOR.MINOR.PATCH"`,
+assuming the crate uses docs.rs for its primary API documentation.
+
+The `html_root_url` attribute tells rustdoc how to create URLs to
+items in the crate when compiling downstream crates. Without it, links
+in the documentation of crates that depend on your crate will be
+incorrect.
+
+```rust
+#![doc(html_root_url = "https://docs.rs/log/0.3.8")]
+```
+
+Because this URL contains an exact version number, it must be kept in
+sync with the version number in `Cargo.toml`. The [`version-sync`]
+crate can help with this by letting you add an integration test that
+fails if the `html_root_url` version number is out of sync with the
+crate version.
+
+[`version-sync`]: https://crates.io/crates/version-sync
+
+If you do not like that mechanism, it is recommended to add a comment
+to the `Cargo.toml` version key reminding yourself to keep the two
+updated together, like:
+
+```toml
+version = "0.3.8" # remember to update html_root_url
+```
+
 
 <a id="c-relnotes"></a>
 ## Release notes document all significant changes (C-RELNOTES)