+2

.github/workflows/ci.yml

reviewed

··· 1 1 + # TODO: still need cross platform E2E testing 2 2 + 1 3 name: CI 2 4 3 5 on:

+8 -28

Cargo.lock

reviewed

··· 636 636 ] 637 637 638 638 [[package]] 639 639 - name = "faster-hex" 640 640 - version = "0.9.0" 641 641 - source = "registry+https://github.com/rust-lang/crates.io-index" 642 642 - checksum = "a2a2b11eda1d40935b26cf18f6833c526845ae8c41e58d09af6adeb6f0269183" 643 643 - dependencies = [ 644 644 - "serde", 645 645 - ] 646 646 - 647 647 - [[package]] 648 639 name = "fastrand" 649 640 version = "2.3.0" 650 641 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 865 856 866 857 [[package]] 867 858 name = "gix-features" 868 868 - version = "0.40.0" 859 859 + version = "0.41.0" 869 860 source = "registry+https://github.com/rust-lang/crates.io-index" 870 870 - checksum = "8bfdd4838a8d42bd482c9f0cb526411d003ee94cc7c7b08afe5007329c71d554" 861 861 + checksum = "729b7e708352a35b2b37ab39cbc7a2b9d22f8386808a10b6ea7dd4cd1cf817cd" 871 862 dependencies = [ 872 872 - "gix-hash", 873 863 "gix-trace", 874 864 "libc", 875 865 ] 876 866 877 867 [[package]] 878 878 - name = "gix-hash" 879 879 - version = "0.16.0" 880 880 - source = "registry+https://github.com/rust-lang/crates.io-index" 881 881 - checksum = "e81c5ec48649b1821b3ed066a44efb95f1a268b35c1d91295e61252539fbe9f8" 882 882 - dependencies = [ 883 883 - "faster-hex", 884 884 - "thiserror 2.0.12", 885 885 - ] 886 886 - 887 887 - [[package]] 888 868 name = "gix-path" 889 889 - version = "0.10.14" 869 869 + version = "0.10.15" 890 870 source = "registry+https://github.com/rust-lang/crates.io-index" 891 891 - checksum = "c40f12bb65a8299be0cfb90fe718e3be236b7a94b434877012980863a883a99f" 871 871 + checksum = "f910668e2f6b2a55ff35a1f04df88a1a049f7b868507f4cbeeaa220eaba7be87" 892 872 dependencies = [ 893 873 "bstr", 894 874 "gix-trace", ··· 905 885 906 886 [[package]] 907 887 name = "gix-url" 908 908 - version = "0.29.0" 888 888 + version = "0.30.0" 909 889 source = "registry+https://github.com/rust-lang/crates.io-index" 910 910 - checksum = "29218c768b53dd8f116045d87fec05b294c731a4b2bdd257eeca2084cc150b13" 890 890 + checksum = "48dfe23f93f1ddb84977d80bb0dd7aa09d1bf5d5afc0c9b6820cccacc25ae860" 911 891 dependencies = [ 912 892 "bstr", 913 893 "gix-features", ··· 1515 1495 1516 1496 [[package]] 1517 1497 name = "mdbook" 1518 1518 - version = "0.4.47" 1498 1498 + version = "0.4.48" 1519 1499 source = "registry+https://github.com/rust-lang/crates.io-index" 1520 1520 - checksum = "7e1a8fe3a4a01f28dab245c474cb7b95ccb4d3d2f17a5419a3d949f474c45e84" 1500 1500 + checksum = "8b6fbb4ac2d9fd7aa987c3510309ea3c80004a968d063c42f0d34fea070817c1" 1521 1501 dependencies = [ 1522 1502 "anyhow", 1523 1503 "chrono",

+2 -2

Cargo.toml

reviewed

··· 24 24 env_logger = "0.11.6" 25 25 insta = { version = "1.40.0", features = ["yaml"] } 26 26 log = "0.4.26" 27 27 - mdbook = { version = "0.4.47", default-features = false } 27 27 + mdbook = { version = "0.4.48", default-features = false } 28 28 miette = { version = "7.5.0", features = [ 29 29 "fancy-no-backtrace", 30 30 ], default-features = false } ··· 42 42 util-testing = { path = "utils/testing" } 43 43 44 44 [workspace.metadata.bin] 45 45 - mdbook = { version = "0.4.47" } 45 45 + mdbook = { version = "0.4.48" } 46 46 mdbook-alerts = { version = "0.7.0" }

+1 -1

crates/mdbookkit/Cargo.toml

reviewed

··· 31 31 dirs = { version = "6.0.0", optional = true } 32 32 env_logger = { workspace = true, optional = true } 33 33 git2 = { version = "0.20.1", default-features = false, optional = true } 34 34 - gix-url = { version = "0.29.0", optional = true } 34 34 + gix-url = { version = "0.30.0", optional = true } 35 35 indicatif = { version = "0.17.11", optional = true } 36 36 log = { workspace = true } 37 37 lsp-types = { version = "0.95.0", optional = true }

+78 -55

crates/mdbookkit/src/bin/link_forever/git.rs

reviewed

··· 1 1 - use anyhow::{bail, Context, Result}; 1 1 + use anyhow::{anyhow, bail, Context, Result}; 2 2 use git2::{DescribeOptions, Repository}; 3 3 use mdbook::preprocess::PreprocessorContext; 4 4 use tap::{Pipe, Tap, TapFallible}; ··· 6 6 7 7 use crate::{ 8 8 env::{config_from_book, smart_punctuation}, 9 9 - log_debug, log_warning, 9 9 + log_debug, 10 10 markdown::mdbook_markdown, 11 11 }; 12 12 13 13 use super::{Config, CustomPermalink, Environment, GitHubPermalink, PermalinkFormat}; 14 14 15 15 impl Environment { 16 16 - pub fn from_book(book: &PreprocessorContext) -> Result<Self> { 17 17 - let repo = Repository::open_from_env() 16 16 + pub fn try_from_env(book: &PreprocessorContext) -> Result<Result<Self>> { 17 17 + let repo = match Repository::open_from_env() 18 18 .context("preprocessor requires a git repository to work") 19 19 - .context("failed to find a git repository")?; 19 19 + .context("failed to find a git repository") 20 20 + { 21 21 + Ok(repo) => repo, 22 22 + Err(err) => return Ok(Err(err)), 23 23 + }; 20 24 21 25 let vcs_root = repo 22 26 .workdir() ··· 41 45 let Some(reference) = 42 46 get_head(&repo).context("failed to get a tag or commit id to HEAD")? 43 47 else { 44 44 - return Ok(Self { 45 45 - book_src, 46 46 - vcs_root, 47 47 - fmt_link: Box::new(GitNotConfigured::NoCommit), 48 48 - markdown, 49 49 - config, 50 50 - }); 48 48 + return Ok(Err(anyhow!("no commit found in this repo"))); 51 49 }; 52 50 53 51 let fmt_link: Box<dyn PermalinkFormat> = { ··· 59 57 reference, 60 58 } 61 59 .pipe(Box::new) 62 62 - } else if let Ok(github) = find_github_repo(&repo, &book.config) 63 63 - .map(|(owner, repo)| GitHubPermalink::new(&owner, &repo, &reference)) 64 64 - .context("failed to determine GitHub url for permalinks") 65 65 - .tap_err(log_warning!(detailed)) 66 66 - .tap_err(|_| { 67 67 - log::warn!("help: set `output.html.git-repository-url` to a GitHub url"); 68 68 - log::warn!("or use `preprocessor.link-forever.repo-url-template`") 69 69 - }) 70 70 - { 71 71 - Box::new(github) 72 60 } else { 73 73 - Box::new(GitNotConfigured::NoRemote) 61 61 + let repo = match find_git_remote(&repo, &book.config)? { 62 62 + Ok(repo) => repo, 63 63 + Err(err) => { 64 64 + return err 65 65 + .context("help: or use `repo-url-template` option") 66 66 + .context("help: set `output.html.git-repository-url` to a GitHub url") 67 67 + .context("failed to determine GitHub url to use for permalinks") 68 68 + .pipe(Err) 69 69 + .pipe(Ok) 70 70 + } 71 71 + }; 72 72 + let (owner, repo) = remote_as_github(repo.as_ref()) 73 73 + .with_context(|| match repo { 74 74 + RepoSource::Config(..) => "in `output.html.git-repository-url`", 75 75 + RepoSource::Remote(..) => "from git remote \"origin\"", 76 76 + }) 77 77 + .context("help: use `repo-url-template` option for a custom remote") 78 78 + .context("failed to parse git remote url")?; 79 79 + GitHubPermalink::new(&owner, &repo, &reference).pipe(Box::new) 74 80 } 75 81 }; 76 82 77 77 - Ok(Self { 83 83 + Ok(Ok(Self { 78 84 book_src, 79 85 vcs_root, 80 86 fmt_link, 81 87 markdown, 82 88 config, 83 83 - }) 89 89 + })) 90 90 + } 91 91 + } 92 92 + 93 93 + enum RepoSource { 94 94 + Config(gix_url::Url), 95 95 + Remote(gix_url::Url), 96 96 + } 97 97 + 98 98 + impl AsRef<gix_url::Url> for RepoSource { 99 99 + fn as_ref(&self) -> &gix_url::Url { 100 100 + match self { 101 101 + Self::Config(u) => u, 102 102 + Self::Remote(u) => u, 103 103 + } 84 104 } 85 105 } 86 106 ··· 89 109 Ok(head) => head, 90 110 Err(err) => { 91 111 log::debug!("{err}"); 92 92 - log::info!("no commit yet, will not generate permalinks"); 93 112 return Ok(None); 94 113 } 95 114 }; ··· 111 130 } 112 131 } 113 132 114 114 - fn find_github_repo(repo: &Repository, config: &mdbook::Config) -> Result<(String, String)> { 115 115 - let url = if let Some(url) = config 133 133 + fn find_git_remote(repo: &Repository, config: &mdbook::Config) -> Result<Result<RepoSource>> { 134 134 + if let Some(url) = config 116 135 .get_deserialized_opt::<String, _>("output.html.git-repository-url") 117 136 .context("failed to get `output.html.git-repository-url`")? 118 137 { 119 119 - gix_url::parse(url.as_str().into()) 138 138 + gix_url::parse(url.as_str().into())? 139 139 + .pipe(RepoSource::Config) 140 140 + .pipe(Ok) 141 141 + .pipe(Ok) 120 142 } else { 121 121 - repo.find_remote("origin") 122 122 - .context("no such remote `origin`")? 123 123 - .url() 124 124 - .context("remote `origin` does not have a url")? 125 125 - .pipe(|url| gix_url::parse(url.into())) 143 143 + let repo = match repo 144 144 + .find_remote("origin") 145 145 + .context("no such remote `origin`") 146 146 + { 147 147 + Ok(repo) => repo, 148 148 + Err(err) => return Ok(Err(err)), 149 149 + }; 150 150 + let repo = match repo.url() { 151 151 + Some(url) => url, 152 152 + None => return Ok(Err(anyhow!("remote `origin` does not have a url"))), 153 153 + }; 154 154 + gix_url::parse(repo.into())? 155 155 + .pipe(RepoSource::Remote) 156 156 + .pipe(Ok) 157 157 + .pipe(Ok) 126 158 } 127 127 - .context("failed to parse remote url")?; 159 159 + } 128 160 161 161 + fn remote_as_github(url: &gix_url::Url) -> Result<(String, String)> { 129 162 let Some(host) = url.host() else { 130 163 bail!("remote url does not have a host") 131 164 }; 132 165 133 166 if host != "github.com" && !host.ends_with(".github.com") { 134 134 - bail!("unsupported remote {host:?}") 167 167 + bail!("unsupported remote {host:?}, only `github.com` is supported") 135 168 } 136 169 137 170 let path = url.path.to_string(); ··· 151 184 Ok((owner.to_owned(), repo.to_owned())) 152 185 } 153 186 154 154 - enum GitNotConfigured { 155 155 - NoCommit, 156 156 - NoRemote, 157 157 - } 158 158 - 159 159 - impl PermalinkFormat for GitNotConfigured { 160 160 - fn link_to(&self, _: &str) -> Result<Url> { 161 161 - match self { 162 162 - Self::NoCommit => bail!("no commit found in this repo"), 163 163 - Self::NoRemote => bail!("remote git url not configured"), 164 164 - } 165 165 - } 166 166 - } 167 167 - 168 187 #[cfg(test)] 169 188 mod tests { 170 189 use anyhow::Result; 171 190 use git2::Repository; 172 191 173 173 - use super::find_github_repo; 192 192 + use super::{find_git_remote, remote_as_github}; 174 193 175 194 #[test] 176 195 fn test_github_url_from_book() -> Result<()> { ··· 180 199 "# 181 200 .parse::<mdbook::Config>()?; 182 201 let repo = Repository::open_from_env()?; 183 183 - let (owner, repo) = find_github_repo(&repo, &config)?; 202 202 + let repo = find_git_remote(&repo, &config)??; 203 203 + let (owner, repo) = remote_as_github(repo.as_ref())?; 184 204 assert_eq!(owner, "lorem"); 185 205 assert_eq!(repo, "ipsum"); 186 206 Ok(()) ··· 190 210 fn test_github_url_from_repo() -> Result<()> { 191 211 let config = "".parse::<mdbook::Config>()?; 192 212 let repo = Repository::open_from_env()?; 193 193 - let (_, repo) = find_github_repo(&repo, &config)?; 213 213 + let repo = find_git_remote(&repo, &config)??; 214 214 + let (_, repo) = remote_as_github(repo.as_ref())?; 194 215 assert_eq!(repo, env!("CARGO_PKG_NAME")); 195 216 Ok(()) 196 217 } ··· 203 224 "# 204 225 .parse::<mdbook::Config>()?; 205 226 let repo = Repository::open_from_env()?; 206 206 - let (owner, repo) = find_github_repo(&repo, &config)?; 227 227 + let repo = find_git_remote(&repo, &config)??; 228 228 + let (owner, repo) = remote_as_github(repo.as_ref())?; 207 229 assert_eq!(owner, "lorem"); 208 230 assert_eq!(repo, "ipsum"); 209 231 Ok(()) ··· 219 241 .parse::<mdbook::Config>() 220 242 .unwrap(); 221 243 let repo = Repository::open_from_env().unwrap(); 222 222 - let _url = find_github_repo(&repo, &config).unwrap(); 244 244 + let repo = find_git_remote(&repo, &config).unwrap().unwrap(); 245 245 + let _ = remote_as_github(repo.as_ref()).unwrap(); 223 246 } 224 247 }

+24 -10

crates/mdbookkit/src/bin/link_forever/main.rs

reviewed

··· 1 1 - use std::{collections::HashMap, io::Write}; 1 1 + use std::collections::HashMap; 2 2 3 3 - use anyhow::Result; 3 3 + use anyhow::{Context, Result}; 4 4 use clap::{Parser, Subcommand}; 5 5 use console::colors_enabled_stderr; 6 6 use log::LevelFilter; 7 7 + use tap::TapFallible; 8 8 + 7 9 use mdbookkit::{ 8 10 bin::link_forever::{Environment, Pages}, 9 11 diagnostics::Issue, 10 10 - env::{book_from_stdin, for_each_chapter_mut, iter_chapters}, 12 12 + env::{book_from_stdin, book_into_stdout, for_each_chapter_mut, iter_chapters}, 11 13 log_warning, 12 14 logging::{is_logging, ConsoleLogger}, 13 15 }; 14 14 - use tap::TapFallible; 15 16 16 17 fn main() -> Result<()> { 17 18 ConsoleLogger::install("link-forever"); ··· 21 22 None => {} 22 23 } 23 24 24 24 - let (context, mut book) = book_from_stdin()?; 25 25 + let (context, mut book) = book_from_stdin().context("failed to parse book content")?; 25 26 26 26 - let env = Environment::from_book(&context)?; 27 27 + let env = match Environment::try_from_env(&context) 28 28 + .context("failed to initialize `mdbook-link-forever`")? 29 29 + { 30 30 + Ok(env) => env, 31 31 + Err(err) => { 32 32 + log::warn!("{:?}", err.context("preprocessor will be disabled")); 33 33 + return book_into_stdout(&book); 34 34 + } 35 35 + }; 27 36 28 37 let mut content = Pages::new(env.markdown); 29 38 30 39 for (path, ch) in iter_chapters(&book) { 31 31 - let url = env.book_src.join(&path.to_string_lossy())?; 32 32 - content.insert(url, &ch.content)?; 40 40 + let url = env 41 41 + .book_src 42 42 + .join(&path.to_string_lossy()) 43 43 + .context("could not read path as a url")?; 44 44 + content 45 45 + .insert(url, &ch.content) 46 46 + .with_context(|| path.display().to_string()) 47 47 + .context("failed to parse Markdown source:")?; 33 48 } 34 49 35 50 env.resolve(&mut content); ··· 61 76 } 62 77 }); 63 78 64 64 - let output = serde_json::to_string(&book)?; 65 65 - std::io::stdout().write_all(output.as_bytes())?; 79 79 + book_into_stdout(&book)?; 66 80 67 81 env.config.fail_on_warnings.check(status.level())?; 68 82

+1 -1

crates/mdbookkit/src/bin/link_forever/mod.rs

reviewed

··· 57 57 } else { 58 58 base.join(&link.link) 59 59 } 60 60 - .context("couldn't derive url") 60 60 + .context("could not derive url") 61 61 .tap_err(log_debug!()); 62 62 63 63 let Ok(file_url) = file else {

+2 -2

crates/mdbookkit/src/bin/rustdoc_link/cache.rs

reviewed

··· 14 14 15 15 use crate::log_debug; 16 16 17 17 - use super::{env::Environment, link::ItemLinks, page::Pages, Resolver}; 17 17 + use super::{env::Environment, link::ItemLinks, page::Pages, url::UrlToPath, Resolver}; 18 18 19 19 #[allow(async_fn_in_trait)] 20 20 pub trait Cache: DeserializeOwned + Serialize { ··· 156 156 } 157 157 158 158 async fn read_dep(url: Url) -> Result<(String, String)> { 159 159 - let content = tokio::fs::read_to_string(&url.path()).await?; 159 159 + let content = tokio::fs::read_to_string(&url.to_path()?).await?; 160 160 Ok((url.to_string(), content)) 161 161 } 162 162

+16 -8

crates/mdbookkit/src/bin/rustdoc_link/client.rs

reviewed

··· 38 38 env::Environment, 39 39 link::ItemLinks, 40 40 sync::{EventSampler, EventSampling}, 41 41 + url::UrlToPath, 41 42 }; 42 43 43 44 /// LSP client to talk to rust-analyzer. ··· 77 78 Ok(opened) 78 79 } 79 80 80 80 - pub async fn stop(self) -> Result<Environment> { 81 81 + pub async fn stop(self) -> Environment { 81 82 if let Some(server) = self.server.into_inner() { 82 82 - server.dispose().await?; 83 83 + server 84 84 + .dispose() 85 85 + .await 86 86 + .context("failed to properly stop rust-analyzer") 87 87 + .tap_err(log_warning!()) 88 88 + .ok(); 83 89 } 84 84 - Ok(self.env) 90 90 + self.env 85 91 } 86 92 87 93 pub async fn drop(self: Arc<Self>) -> Result<Environment> { 88 94 let Some(this) = Arc::into_inner(self) else { 89 95 bail!("attempted to shutdown a client that is still referenced") 90 96 }; 91 91 - this.stop().await 97 97 + Ok(this.stop().await) 92 98 } 93 99 } 94 100 ··· 120 126 percent_indexed: Option<u32>, 121 127 } 122 128 123 123 - fn on_progress(state: &mut State, progress: ProgressParams) { 129 129 + fn probe_progress(state: &mut State, progress: ProgressParams) { 124 130 match indexing_progress(&progress) { 125 131 Some(WorkDoneProgress::Begin(begin)) => { 126 132 state.percent_indexed = Some(0); ··· 147 153 let spurious = if let Some(msg) = &report.message { 148 154 // HACK: invalidate progress reports that say "0/1 (crate name)" 149 155 // because RA isn't actually indexing everything at this point 150 150 - msg.contains("0/1") 156 156 + msg.starts_with("0/1 (") 151 157 } else { 152 158 // also ignore indexing runs that went from 0 to a 100 153 159 *indexed == 0 && update == 100 154 160 }; 155 161 156 162 if spurious { 163 163 + log::debug!("ignoring spurious rust-analyzer progress"); 157 164 state.percent_indexed = None; 158 165 return; 159 166 } ··· 196 203 197 204 router 198 205 .notification::<Progress>(|state, progress| { 199 199 - on_progress(state, progress); 206 206 + log::trace!("{progress:#?}"); 207 207 + probe_progress(state, progress); 200 208 ControlFlow::Continue(()) 201 209 }) 202 210 .notification::<PublishDiagnostics>(|_, diagnostics| { ··· 221 229 222 230 let proc = env 223 231 .command()? 224 224 - .current_dir(env.crate_dir.path()) 232 232 + .current_dir(env.crate_dir.to_path()?) 225 233 .stdin(Stdio::piped()) 226 234 .stdout(Stdio::piped()) 227 235 .stderr(Stdio::inherit())

+30 -29

crates/mdbookkit/src/bin/rustdoc_link/env.rs

reviewed

··· 4 4 sync::Arc, 5 5 }; 6 6 7 7 - use anyhow::{anyhow, Context, Result}; 7 7 + use anyhow::{anyhow, bail, Context, Result}; 8 8 use cargo_toml::{Manifest, Product}; 9 9 #[cfg(feature = "common-cli")] 10 10 use clap::ValueHint; ··· 140 140 .manifest_dir 141 141 .clone() 142 142 .map(Ok) 143 143 - .unwrap_or_else(std::env::current_dir)? 144 144 - .canonicalize()?; 143 143 + .unwrap_or_else(std::env::current_dir) 144 144 + .context("failed to get the current working directory")? 145 145 + .canonicalize() 146 146 + .context("failed to resolve `manifest-dir` to a path")?; 145 147 146 148 let (crate_dir, entrypoint) = { 147 147 - let manifest_path = LocateProject::package(&cwd)?.root; 149 149 + let manifest_path = LocateProject::package(&cwd) 150 150 + .context("preprocessor requires a Cargo project to run rust-analyzer") 151 151 + .context("failed to determine the current Cargo project")? 152 152 + .root; 148 153 149 149 - let manifest = { 150 150 - let mut manifest = Manifest::from_path(&manifest_path)?; 151 151 - manifest.complete_from_path(&manifest_path)?; 152 152 - manifest 153 153 - }; 154 154 + let manifest = Manifest::from_path(&manifest_path) 155 155 + .and_then(|mut m| m.complete_from_path(&manifest_path).and(Ok(m))) 156 156 + .context("failed to read Cargo.toml")?; 154 157 155 158 let crate_dir = manifest_path 156 159 .parent() ··· 169 172 let entry = crate_dir.join(bin)?; 170 173 Ok((crate_dir, entry)) 171 174 } else { 172 172 - Err(anyhow!( 175 175 + let err = Err(anyhow!( 173 176 "help: resolved Cargo.toml is {}", 174 177 manifest_path.display() 175 175 - )) 176 176 - .pipe(|r| { 177 177 - if manifest.workspace.is_some() { 178 178 - r.context("help: to use in a workspace, set `manifest-dir` option to root of a member crate") 179 179 - } else { 180 180 - r 181 181 - } 182 182 - }) 178 178 + )); 179 179 + if manifest.workspace.is_some() { 180 180 + err.context("help: to use in a workspace, set `manifest-dir` option to root of a member crate") 181 181 + } else { 182 182 + err 183 183 + } 183 184 .context("Cargo.toml does not have any lib or bin target") 184 185 } 185 186 }?; 186 187 187 187 - let source_dir = LocateProject::workspace(cwd)? 188 188 + let source_dir = LocateProject::workspace(cwd) 189 189 + .context("failed to locate the current Cargo project")? 188 190 .root 189 191 .parent() 190 192 .unwrap() ··· 294 296 295 297 impl LocateProject { 296 298 fn package<P: AsRef<Path>>(cwd: P) -> Result<Self> { 297 297 - std::process::Command::new(env!("CARGO")) 299 299 + std::process::Command::new("cargo") 298 300 .arg("locate-project") 299 301 .arg("--message-format=json") 300 302 .current_dir(cwd) 301 301 - .output()? 302 302 - .pipe(Self::parse) 303 303 + .output() 304 304 + .context("failed to run `cargo locate-project`, is cargo installed?") 305 305 + .and_then(Self::parse) 303 306 } 304 307 305 308 fn workspace<P: AsRef<Path>>(cwd: P) -> Result<Self> { 306 306 - std::process::Command::new(env!("CARGO")) 309 309 + std::process::Command::new("cargo") 307 310 .arg("locate-project") 308 311 .arg("--message-format=json") 309 312 .arg("--workspace") 310 313 .current_dir(cwd) 311 311 - .output()? 312 312 - .pipe(Self::parse) 314 314 + .output() 315 315 + .context("failed to run `cargo locate-project`, is cargo installed?") 316 316 + .and_then(Self::parse) 313 317 } 314 318 315 319 fn parse(output: std::process::Output) -> Result<Self> { ··· 318 322 .pipe(|outout| serde_json::from_str::<Self>(&outout))? 319 323 .pipe(Ok) 320 324 } else { 321 321 - anyhow!(String::from_utf8_lossy(&output.stderr).into_owned()) 322 322 - .context("help: a Cargo project is needed to run rust-analyzer in") 323 323 - .context("failed to locate a Cargo project") 324 324 - .pipe(Err) 325 325 + bail!(String::from_utf8_lossy(&output.stderr).into_owned()); 325 326 } 326 327 } 327 328 }

+56 -43

crates/mdbookkit/src/bin/rustdoc_link/main.rs

reviewed

··· 1 1 - use std::{ 2 2 - collections::HashMap, 3 3 - io::{Read, Write}, 4 4 - }; 1 1 + use std::{collections::HashMap, io::Write}; 5 2 6 6 - use anyhow::Result; 3 3 + use anyhow::{Context, Result}; 7 4 use clap::{Parser, Subcommand}; 8 5 use console::colors_enabled_stderr; 9 6 use log::LevelFilter; 7 7 + use mdbook::preprocess::PreprocessorContext; 10 8 use tap::{Pipe, TapFallible}; 11 9 12 10 use mdbookkit::{ ··· 17 15 }, 18 16 diagnostics::Issue, 19 17 env::{ 20 20 - book_from_stdin, config_from_book, for_each_chapter_mut, iter_chapters, smart_punctuation, 18 18 + book_from_stdin, book_into_stdout, config_from_book, for_each_chapter_mut, iter_chapters, 19 19 + smart_punctuation, string_from_stdin, 21 20 }, 22 21 log_warning, 23 22 logging::{is_logging, ConsoleLogger}, ··· 54 53 } 55 54 56 55 async fn mdbook() -> Result<()> { 57 57 - let (context, mut book) = book_from_stdin()?; 58 58 - 59 59 - let config = { 60 60 - let mut config = config_from_book::<Config>(&context.config, "rustdoc-link")?; 61 61 - 62 62 - if let Some(path) = config.manifest_dir { 63 63 - config.manifest_dir = Some(context.root.join(path)) 64 64 - } else { 65 65 - config.manifest_dir = Some(context.root.clone()) 66 66 - } 67 67 - 68 68 - if let Some(path) = config.cache_dir { 69 69 - config.cache_dir = Some(context.root.join(path)) 70 70 - } 56 56 + let (context, mut book) = book_from_stdin().context("failed to parse book content")?; 71 57 72 72 - config.smart_punctuation = smart_punctuation(&context.config); 58 58 + let config = config(&context).context("failed to read preprocessor config from book.toml")?; 73 59 74 74 - config 75 75 - }; 76 76 - 77 77 - let client = Client::new(Environment::new(config)?); 60 60 + let client = Environment::new(config) 61 61 + .context("failed to initialize `mdbook-rustdoc-link`")? 62 62 + .pipe(Client::new); 78 63 79 64 let cached = FileCache::load(client.env()).await.ok(); 80 65 ··· 82 67 83 68 for (path, ch) in iter_chapters(&book) { 84 69 let stream = client.env().markdown(&ch.content).into_offset_iter(); 85 85 - content.read(path.clone(), &ch.content, stream)?; 70 70 + content 71 71 + .read(path.clone(), &ch.content, stream) 72 72 + .with_context(|| path.display().to_string()) 73 73 + .context("failed to parse Markdown source:")?; 86 74 } 87 75 88 76 if let Some(cached) = cached { 89 77 cached.resolve(&mut content).await.ok(); 90 78 } 91 79 92 92 - client.resolve(&mut content).await?; 80 80 + client 81 81 + .resolve(&mut content) 82 82 + .await 83 83 + .context("failed to resolve some links")?; 93 84 94 85 let mut result = iter_chapters(&book) 95 86 .filter_map(|(path, _)| { 96 96 - content 87 87 + let output = content 97 88 .emit(path, &client.env().emit_config()) 98 89 .tap_err(log_warning!()) 99 99 - .ok() 100 100 - .map(|output| (path.clone(), output.to_string())) 90 90 + .ok()?; 91 91 + Some((path.clone(), output.to_string())) 101 92 }) 102 93 .collect::<HashMap<_, _>>(); 103 94 104 104 - let env = client.stop().await?; 95 95 + let env = client.stop().await; 105 96 106 97 let status = content 107 98 .reporter() ··· 123 114 } 124 115 }); 125 116 126 126 - let output = serde_json::to_string(&book)?; 127 127 - std::io::stdout().write_all(output.as_bytes())?; 117 117 + book_into_stdout(&book)?; 128 118 129 119 env.config.fail_on_warnings.check(status.level())?; 130 120 131 121 Ok(()) 132 122 } 133 123 134 134 - async fn markdown(options: Config) -> Result<()> { 135 135 - let client = Client::new(Environment::new(options)?); 124 124 + async fn markdown(config: Config) -> Result<()> { 125 125 + let client = Environment::new(config) 126 126 + .context("failed to initialize")? 127 127 + .pipe(Client::new); 136 128 137 137 - let source = Vec::new() 138 138 - .pipe(|mut buf| std::io::stdin().read_to_end(&mut buf).and(Ok(buf)))? 139 139 - .pipe(String::from_utf8)?; 129 129 + let source = string_from_stdin().context("failed to read Markdown source from stdin")?; 140 130 141 131 let stream = client.env().markdown(&source).into_offset_iter(); 142 132 143 143 - let mut content = Pages::one(&source, stream)?; 133 133 + let mut content = Pages::one(&source, stream).context("failed to parse Markdown source")?; 144 134 145 135 if let Ok(cached) = FileCache::load(client.env()).await { 146 136 cached.resolve(&mut content).await.ok(); 147 137 } 148 138 149 149 - client.resolve(&mut content).await?; 139 139 + client 140 140 + .resolve(&mut content) 141 141 + .await 142 142 + .context("failed to resolve some links")?; 150 143 151 151 - let env = client.stop().await?; 144 144 + let env = client.stop().await; 152 145 153 146 let status = content 154 147 .reporter() ··· 164 157 FileCache::save(&env, &content).await.ok(); 165 158 } 166 159 167 167 - let output = content.get(&env.emit_config())?.to_string(); 168 168 - std::io::stdout().write_all(output.as_bytes())?; 160 160 + content 161 161 + .get(&env.emit_config()) 162 162 + .map(|emit| emit.to_string()) 163 163 + .and_then(|output| Ok(std::io::stdout().write_all(output.as_bytes())?))?; 169 164 170 165 env.config.fail_on_warnings.check(status.level())?; 171 166 172 167 Ok(()) 173 168 } 169 169 + 170 170 + fn config(context: &PreprocessorContext) -> Result<Config> { 171 171 + let mut config = config_from_book::<Config>(&context.config, "rustdoc-link")?; 172 172 + 173 173 + if let Some(path) = config.manifest_dir { 174 174 + config.manifest_dir = Some(context.root.join(path)) 175 175 + } else { 176 176 + config.manifest_dir = Some(context.root.clone()) 177 177 + } 178 178 + 179 179 + if let Some(path) = config.cache_dir { 180 180 + config.cache_dir = Some(context.root.join(path)) 181 181 + } 182 182 + 183 183 + config.smart_punctuation = smart_punctuation(&context.config); 184 184 + 185 185 + Ok(config) 186 186 + }

+5 -3

crates/mdbookkit/src/bin/rustdoc_link/mod.rs

reviewed

··· 12 12 mod markdown; 13 13 mod page; 14 14 mod sync; 15 15 + mod url; 15 16 16 17 #[cfg(feature = "rustdoc-link")] 17 18 pub mod cache; ··· 19 20 use crate::{log_debug, logging::spinner, styled}; 20 21 21 22 pub use self::{client::Client, page::Pages}; 22 22 - use self::{item::Item, link::ItemLinks}; 23 23 + use self::{item::Item, link::ItemLinks, url::UrlToPath}; 23 24 24 25 /// Type that can provide links. 25 26 /// ··· 49 50 return Ok(()); 50 51 } 51 52 52 52 - let main = std::fs::read_to_string(self.env().entrypoint.path())?; 53 53 + let main = std::fs::read_to_string(self.env().entrypoint.to_path()?)?; 53 54 54 55 let (context, request) = { 55 56 let mut context = format!("{main}\nfn {UNIQUE_ID} () {{\n"); ··· 109 110 let resolved = doc 110 111 .resolve(p) 111 112 .await 112 112 - .with_context(|| format!("error resolving {p:?}")) 113 113 + .with_context(|| format!("{p:?}")) 114 114 + .context("failed to resolve symbol:") 113 115 .tap_err(log_debug!()) 114 116 .ok(); 115 117 if let Some(resolved) = resolved {

+18

crates/mdbookkit/src/bin/rustdoc_link/url.rs

reviewed

··· 1 1 + use std::path::PathBuf; 2 2 + 3 3 + use anyhow::{bail, Result}; 4 4 + use lsp_types::Url; 5 5 + 6 6 + /// [`Url::to_file_path()`] with an actual [`std::error::Error`]. 7 7 + pub trait UrlToPath { 8 8 + fn to_path(&self) -> Result<PathBuf>; 9 9 + } 10 10 + 11 11 + impl UrlToPath for Url { 12 12 + fn to_path(&self) -> Result<PathBuf> { 13 13 + match self.to_file_path() { 14 14 + Ok(path) => Ok(path), 15 15 + Err(()) => bail!("failed to convert {self} to a file path"), 16 16 + } 17 17 + } 18 18 + }

+20 -3

crates/mdbookkit/src/env.rs

reviewed

··· 1 1 + use std::io::Read; 2 2 + 1 3 use anyhow::{anyhow, Result}; 2 4 use serde::Deserialize; 3 5 use tap::Pipe; ··· 47 49 } 48 50 } 49 51 52 52 + pub fn string_from_stdin() -> Result<String> { 53 53 + Vec::new() 54 54 + .pipe(|mut buf| std::io::stdin().read_to_end(&mut buf).and(Ok(buf)))? 55 55 + .pipe(|buf| Ok(String::from_utf8(buf)?)) 56 56 + } 57 57 + 50 58 #[cfg(feature = "common-cli")] 51 59 pub use book::*; 52 60 #[cfg(feature = "common-cli")] 53 61 mod book { 54 54 - use std::{io::Read, path::PathBuf}; 62 62 + use std::{ 63 63 + io::{Read, Write}, 64 64 + path::PathBuf, 65 65 + }; 55 66 56 67 use anyhow::{Context, Result}; 57 68 use mdbook::{ ··· 74 85 T: DeserializeOwned + Default, 75 86 { 76 87 if let Some(config) = config.get_preprocessor(name) { 77 77 - T::deserialize(toml::Value::Table(config.clone())) 78 78 - .context("failed to read preprocessor config from book.toml")? 88 88 + T::deserialize(toml::Value::Table(config.clone()))? 79 89 } else { 80 90 Default::default() 81 91 } ··· 110 120 let Some(path) = &ch.source_path else { return }; 111 121 func(path.clone(), ch) 112 122 }); 123 123 + } 124 124 + 125 125 + pub fn book_into_stdout(book: &Book) -> Result<()> { 126 126 + serde_json::to_string(&book) 127 127 + .context("failed to serialize book") 128 128 + .and_then(|output| Ok(std::io::stdout().write_all(output.as_bytes())?)) 129 129 + .context("failed to write book to stdout") 113 130 } 114 131 }

-3

crates/mdbookkit/tests/snaps/rustdoc_link/rustdoc-link.snap

reviewed

··· 1 1 --- 2 2 source: crates/mdbookkit/tests/rustdoc_link.rs 3 3 - assertion_line: 31 4 3 expression: output 5 4 --- 6 5 # mdbook-rustdoc-link ··· 81 80 82 81 This project is released under the [Apache 2.0 License](/LICENSE-APACHE.md) and the 83 82 [MIT License](/LICENSE-MIT.md). 84 84 - 85 85 - --- 86 83 87 84 [^1]: Text adapted from [<cite>A Tour of The Rust Standard Library</cite>][tour] 88 85

-2

crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.snap

reviewed

··· 252 252 253 253 <!-- prettier-ignore-end --> 254 254 255 255 - --- 256 256 - 257 255 [^1]: 258 256 rust-analyzer's ability to generate links for enum variants like `Option::Some` was 259 257 improved only somewhat recently: before

+13 -15

crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.stderr.snap

reviewed

··· 265 265 248 │ 266 266 249 │ <!-- prettier-ignore-end --> 267 267 250 │ 268 268 - 251 │ --- 269 269 - 252 │ 270 270 - 253 │ [^1]: 271 271 - 254 │ rust-analyzer's ability to generate links for enum variants like `Option::Some` was 272 272 - 255 │ improved only somewhat recently: before 273 273 - 256 │ [#19246](https://github.com/rust-lang/rust-analyzer/pull/19246), links for variants 274 274 - 257 │ and associated items may only point to the types themselves. If linking to such 275 275 - 258 │ items doesn't seem to work for you, be sure to upgrade to a newer rust-analyzer 276 276 - 259 │ first! 277 277 - 260 │ 278 278 - 261 │ [^2]: 279 279 - 262 │ As of rust-analyzer <ra-version>(version)</ra-version>, links generated for macros 280 280 - 263 │ don't always work. Examples include [`std::format!`] (seen above) and 268 268 + 251 │ [^1]: 269 269 + 252 │ rust-analyzer's ability to generate links for enum variants like `Option::Some` was 270 270 + 253 │ improved only somewhat recently: before 271 271 + 254 │ [#19246](https://github.com/rust-lang/rust-analyzer/pull/19246), links for variants 272 272 + 255 │ and associated items may only point to the types themselves. If linking to such 273 273 + 256 │ items doesn't seem to work for you, be sure to upgrade to a newer rust-analyzer 274 274 + 257 │ first! 275 275 + 258 │ 276 276 + 259 │ [^2]: 277 277 + 260 │ As of rust-analyzer <ra-version>(version)</ra-version>, links generated for macros 278 278 + 261 │ don't always work. Examples include [`std::format!`] (seen above) and 281 279 · ────────┬─────── 282 280 · ╰── https://doc.rust-lang.org/stable/alloc/macros/macro.format.html 283 283 - 264 │ [`tokio::main!`]. For more info, see [Known issues](known-issues.md#macros). 281 281 + 262 │ [`tokio::main!`]. For more info, see [Known issues](known-issues.md#macros). 284 282 · ────────┬─────── 285 283 · ╰── https://docs.rs/tokio-macros/2.5.0/tokio_macros/macro.main.html 286 286 - 265 │ 284 284 + 263 │ 287 285 ╰────

+8 -3

deno.json

reviewed

··· 1 1 { 2 2 - "tasks": { 3 3 - "format": "deno run -A npm:prettier --write docs/app docs/src" 2 2 + "compilerOptions": { 3 3 + "lib": ["esnext", "dom", "deno.ns"], 4 4 + "strict": true 4 5 }, 6 6 + "exclude": ["node_modules", "build", "dist", "target", "docs/app/dist.js"], 5 7 "imports": { 6 8 "esbuild": "npm:esbuild@^0.25.1", 7 9 "prettier": "npm:prettier@^3.5.3" 8 10 }, 9 9 - "nodeModulesDir": "auto" 11 11 + "nodeModulesDir": "auto", 12 12 + "tasks": { 13 13 + "format": "deno run -A npm:prettier --write docs/app docs/src" 14 14 + } 10 15 }

+1

docs/.gitignore

reviewed

··· 1 1 /build 2 2 /app/dist.css 3 3 + /app/dist.js 3 4 /src/app

+1 -1

docs/Cargo.toml

reviewed

··· 12 12 [dependencies] 13 13 anyhow = { workspace = true } 14 14 clap = { workspace = true } 15 15 - gix-url = { version = "0.29.0" } 15 15 + gix-url = { version = "0.30.0" } 16 16 miette = { workspace = true } 17 17 serde = { workspace = true } 18 18 serde_json = { workspace = true }

+32 -7

docs/app/build/build.ts

reviewed

··· 4 4 5 5 const relpath = (path: string) => new URL(path, import.meta.url).pathname; 6 6 7 7 + try { 8 8 + await Deno.remove(relpath("../../src/app"), { recursive: true }); 9 9 + } catch { 10 10 + // recursive: true is supposed to make it not throw ... 11 11 + } 12 12 + 7 13 const built = await esbuild.build({ 8 14 bundle: true, 15 15 + format: "esm", 9 16 target: ["chrome93", "firefox93", "safari15", "es2020"], 10 17 platform: "browser", 11 18 plugins: [remoteCSS()], 12 12 - entryPoints: [relpath("../main.css")], 19 19 + entryPoints: [relpath("../main.js"), relpath("../main.css")], 13 20 outdir: relpath("../../src/app"), 14 21 entryNames: "[name]-[hash]", 15 22 metafile: true, 16 23 logLevel: Deno.env.get("CI") ? "info" : undefined, 17 24 }); 18 25 19 19 - // generate an `app/dist.css` for mdBook that actually imports the bundle 26 26 + // generate `app/dist.css` and `app/dist.js` for mdBook that actually imports the bundle 27 27 + 28 28 + const css: string[] = []; 29 29 + const esm: string[] = []; 30 30 + 31 31 + for (const [path, file] of Object.entries(built.metafile.outputs)) { 32 32 + if (file.entryPoint) { 33 33 + const name = JSON.stringify(`./${pathlib.basename(path)}`); 34 34 + switch (path.split(".").pop()) { 35 35 + case "css": 36 36 + css.push(`@import url(${name});`); 37 37 + break; 38 38 + case "js": 39 39 + esm.push(`import(${name});`); 40 40 + break; 41 41 + default: 42 42 + break; 43 43 + } 44 44 + } 45 45 + } 46 46 + 47 47 + await Deno.writeTextFile(relpath("../dist.css"), css.join("\n") + "\n"); 20 48 21 49 await Deno.writeTextFile( 22 22 - relpath("../dist.css"), 23 23 - Object.entries(built.metafile.outputs) 24 24 - .filter(([, file]) => file.entryPoint) 25 25 - .map(([path]) => `@import url(${JSON.stringify(pathlib.basename(path))});`) 26 26 - .join("\n"), 50 50 + relpath("../dist.js"), 51 51 + `document.addEventListener("DOMContentLoaded", () => { ${esm.join("\n")} });`, 27 52 ); 28 53 29 54 function remoteCSS(): esbuild.Plugin {

+26 -20

docs/app/main.css

reviewed

··· 208 208 } 209 209 210 210 .footnote-definition { 211 211 - display: grid; 212 212 - grid-template-columns: max-content auto; 213 213 - gap: 0.5rem; 214 214 - margin-block: 0.5rem; 215 215 - 216 216 - .footnote-definition-label { 217 217 - line-height: 1.8; 211 211 + > p { 212 212 + line-height: 1.6; 218 213 } 219 214 220 220 - > * { 221 221 - display: block; 222 222 - margin: 0; 215 215 + > li:target::before { 216 216 + background-color: #ffb45420; 217 217 + outline: 0.5rem solid #ffb45420; 218 218 + border: none; 219 219 + border-radius: 0; 220 220 + top: 0; 221 221 + bottom: 0; 222 222 + left: -24px; 223 223 + right: 0; 223 224 } 225 225 + } 224 226 225 225 - > p { 226 226 - line-height: 1.6; 227 227 - } 227 227 + :not(h1, h2, h3, h4, h5, h6, .footnote-definition > li):target { 228 228 + background-color: #ffb45420; 229 229 + outline: 0.5rem solid #ffb45420; 228 230 229 229 - > *:not(.footnote-definition-label) { 230 230 - grid-column-start: 2; 231 231 + &.footnote-reference { 232 232 + background-color: #ffb45440; 233 233 + outline: 0.25rem solid #ffb45440; 234 234 + border-radius: 0; 231 235 } 232 236 } 233 237 ··· 237 241 margin: 2rem 0; 238 242 background-color: #3d444d; 239 243 border: 0; 240 240 - } 241 241 - 242 242 - :not(h1, h2, h3, h4, h5, h6):target { 243 243 - background-color: #ffb45420; 244 244 - outline: 0.5rem solid #ffb45420; 245 244 } 246 245 247 246 img, ··· 407 406 408 407 > blockquote { 409 408 padding-inline-start: calc(20px - 0.25rem); 409 409 + } 410 410 + 411 411 + .footnote-definition > li:target::before { 412 412 + top: 0; 413 413 + bottom: 0; 414 414 + left: -40px; 415 415 + width: 100vw; 410 416 } 411 417 412 418 > .mdbook-alerts {

+8

docs/app/main.ts

reviewed

··· 1 1 + document 2 2 + .querySelectorAll<HTMLElement>(".footnote-definition a[href^='#fr-']") 3 3 + .forEach((elem) => { 4 4 + elem.style.marginInlineEnd = "2px"; 5 5 + if (elem.textContent) { 6 6 + elem.textContent = elem.textContent.replaceAll("↩", "↩\ufe0e"); 7 7 + } 8 8 + });

+1

docs/book.toml

reviewed

··· 15 15 16 16 [output.html] 17 17 additional-css = ["app/dist.css"] 18 18 + additional-js = ["app/dist.js"] 18 19 default-theme = "ayu" 19 20 git-repository-icon = "fa-github" 20 21 git-repository-url = "https://github.com/tonywu6/mdbookkit"

-2

docs/src/rustdoc-link.md

reviewed

··· 77 77 This project is released under the [Apache 2.0 License](/LICENSE-APACHE.md) and the 78 78 [MIT License](/LICENSE-MIT.md). 79 79 80 80 - --- 81 81 - 82 80 [^1]: Text adapted from [<cite>A Tour of The Rust Standard Library</cite>][tour] 83 81 84 82 <!-- prettier-ignore-start -->

+6 -13

docs/src/rustdoc-link/caching.md

reviewed

··· 94 94 95 95 Furthermore, the preprocessor relies on the LSP [Work Done 96 96 Progress][lsp-work-done-progress] notifications to know when rust-analyzer has finished 97 97 - cache priming before actually sending out external docs requests. Because rust-analyzer 98 98 - seems to automatically reindex multiple times, a "cooldown" mechanism was implemented, 99 99 - to wait for a hard-coded 500ms after rust-analyzer reports indexing done, before 100 100 - continuing. 97 97 + cache priming, before actually sending out external docs requests. This requires parsing 98 98 + non-structured log messages that rust-analyzer sends out and some debouncing/throttling 99 99 + logic, which is not ideal, see 100 100 + [client.rs](/crates/mdbookkit/src/bin/rustdoc_link/client.rs#L129-L132). 101 101 102 102 - Not doing either of these things causes many links to fail to resolve. 102 102 + Not waiting for indexing to finish and sending out requests too early causes 103 103 + rust-analyzer to respond with empty results. 103 104 104 105 **Questions**: 105 106 ··· 142 143 languages like Rust, and `mdbook` has an explicitly non-incremental architecture, 143 144 perfect for rendering Markdown. This makes them somewhat challenging to work well 144 145 together in a live-reload scenario. 145 145 - 146 146 - > [!NOTE] 147 147 - > 148 148 - > The above is entirely my understanding of how the two projects work, which may have 149 149 - > gross misconceptions or misuse of words. [Feedback of any kind is very welcome 150 150 - > :)][gh-issues] 151 151 - 152 152 - --- 153 146 154 147 [^1]: 155 148 It was mentioned that the [recently updated, salsa-ified rust-analyzer][salsa]

-2

docs/src/rustdoc-link/supported-syntax.md

reviewed

··· 248 248 249 249 <!-- prettier-ignore-end --> 250 250 251 251 - --- 252 252 - 253 251 [^1]: 254 252 rust-analyzer's ability to generate links for enum variants like `Option::Some` was 255 253 improved only somewhat recently: before

-14

tsconfig.json

reviewed

··· 1 1 - { 2 2 - "compilerOptions": { 3 3 - "target": "ESNext", 4 4 - "lib": ["ESNext"], 5 5 - "module": "ESNext", 6 6 - "moduleResolution": "bundler", 7 7 - "moduleDetection": "force", 8 8 - "allowJs": true, 9 9 - "checkJs": true, 10 10 - "strict": true, 11 11 - "noEmit": true 12 12 - }, 13 13 - "exclude": ["node_modules", "build", "dist", "target"] 14 14 - }