From 4fd7076df7d01f3b63022a6f3cfdc3a7cabde243 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Wed, 18 Nov 2020 17:27:46 -0500 Subject: [PATCH] Don't recommend setting html_root_url --- src/checklist.md | 1 - src/documentation.md | 45 -------------------------------------------- 2 files changed, 46 deletions(-) diff --git a/src/checklist.md b/src/checklist.md index 3f3d5ac..763bfec 100644 --- a/src/checklist.md +++ b/src/checklist.md @@ -36,7 +36,6 @@ - [ ] 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)* diff --git a/src/documentation.md b/src/documentation.md index 4060ecd..07dbb72 100644 --- a/src/documentation.md +++ b/src/documentation.md @@ -202,51 +202,6 @@ 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 - -### 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 -``` - -For documentation hosted outside of docs.rs, the value for `html_root_url` is -correct if appending the crate name + index.html takes you to the documentation -of the crate's root module. For example if the documentation of the root module -is located at `"https://api.rocket.rs/rocket/index.html"` then the -`html_root_url` would be `"https://api.rocket.rs"`. - - ## Release notes document all significant changes (C-RELNOTES)