Merge pull request #1578 from ehuss/std-links

Rewrite the automatic std link translation, and switch to automatic links

Author: ehuss

README.md

@@ -61,13 +61,15 @@ To build the Reference locally (in `build/`) and open it in a web
 browser, run:
 
 ```sh
-mdbook build --open
+SPEC_RELATIVE=0 mdbook build --open
 ```
 
 This will open a browser with a websocket live-link to automatically reload whenever the source is updated.
 
-You can also open any current build of the reference by running:
+The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to <https://doc.rust-lang.org/> instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library.
+
+You can also use mdbook's live webserver option, which will automatically rebuild the book and reload your web browser whenever a source file is modified:
 
 ```sh
-mdbook serve --open
+SPEC_RELATIVE=0 mdbook serve --open
 ```

book.toml

@@ -18,7 +18,7 @@ smart-punctuation = true
 edition = "2021"
 
 [preprocessor.spec]
-command = "cargo run --manifest-path mdbook-spec/Cargo.toml"
+command = "cargo run --release --manifest-path mdbook-spec/Cargo.toml"
 
 [build]
 extra-watch-dirs = ["mdbook-spec/src"]

docs/authoring.md

@@ -109,6 +109,15 @@ Explicit namespace disambiguation is also supported:
 [`std::vec`](mod@std::vec)
 ```
 
+Beware there are some limitations, for example:
+
+- Links to rexports from `std_arch` don't work due to <https://github.com/rust-lang/rust/issues/96506>.
+- Links to keywords aren't supported.
+- Links to trait impls where the trait is not in the prelude doesn't work. Traits must be in scope, and there currently isn't a way to add those.
+- If there are multiple generic implementations, it will link to one randomly (see <https://github.com/rust-lang/rust/issues/76895>).
+
+When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`.
+
 [intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html
 
 ### Admonitions

mdbook-spec/Cargo.lock

@@ -13,6 +13,8 @@ anyhow = "1.0.79"
 mdbook = { version = "0.4.36", default-features = false }
 once_cell = "1.19.0"
 pathdiff = "0.2.1"
+# Try to keep in sync with mdbook.
+pulldown-cmark = { version = "0.10.3", default-features = false }
 regex = "1.9.4"
 semver = "1.0.21"
 serde_json = "1.0.113"

mdbook-spec/Cargo.toml

@@ -154,7 +154,6 @@ impl Preprocessor for Spec {
             }
             ch.content = self.rule_definitions(&ch, &mut found_rules);
             ch.content = self.admonitions(&ch);
-            ch.content = std_links::std_links(&ch);
         });
         // This is a separate pass because it relies on the modifications of
         // the previous passes.
@@ -167,6 +166,10 @@ impl Preprocessor for Spec {
             }
             ch.content = self.auto_link_references(&ch, &found_rules);
         });
+        // Final pass will resolve everything as a std link (or error if the
+        // link is unknown).
+        std_links::std_links(&mut book);
+
         Ok(book)
     }
 }