-
Notifications
You must be signed in to change notification settings - Fork 726
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
intra doc links instead of relative file paths #2068
Conversation
I ran into a few relative links that didn't work right either in the original context or in the re-exported context. afaict letting Cargo figure out the links works better now. I used the following definitely very robust and obvious invocation: find -name \*.rs -exec sed -i -e ' s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\w\+\.\(\w\+\)\.html@\1super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\w\+\.\(\w\+\)\.html@\1super::super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::super::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/index\.html@\1super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./index\.html@\1super@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\?$@\1super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\w\+\.\(\w\+\)\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/index\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./index\.html@\1self@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\?$@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\w\+\.\(\w\+\)\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/index\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?index\.html@\1self@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\?$@\1self::\2@; s@\(//. \[[^]]*\]:\s\+[A-Za-z_0-9:]\+\)#method\.\(\w\+\)@\1::\2@; ' {} +
I didn't sed very cleverly so a lot of stuff came out wrong or at least ambiguous and awkward, unsurprisingly, so here is some manual fixing-up. afaict `Callsite:id` hasn't existed in a long time so I went and also removed other mentions of it.
idk what to do about html links though, there's a bunch of stuff inside weird tags where markdown doesn't apply |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
At a glance, this looks good to me --- thanks for working on this. I believe the Netlify docs preview CI job would fail if any of the new links were broken, so I don't think we actually need to manually check them.
Regarding
idk what to do about html links though, there's a bunch of stuff inside weird tags where markdown doesn't apply
I don't think we can do anything about those here; the explicit HTML links are used because RustDoc appears to not parse markdown inside of HTML tags. So, I don't think those can easily be made intra-doc links.
@@ -88,12 +88,12 @@ | |||
//! | |||
//! The [`non_blocking` module][non_blocking]'s documentation provides more detail on how to use `non_blocking`. | |||
//! | |||
//! [non_blocking]: ./non_blocking/index.html | |||
//! [non_blocking]: mod@non_blocking | |||
//! [write]: https://doc.rust-lang.org/std/io/trait.Write.html |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can we also apply this treatment to docs links to the standard library? it would be fine to do that in a separate PR, though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
definitely (tho prefer separate pr), i'm gonna read up more on how those links work for cross crate references :v
👍 yeah cargo doc complains about broken links and i pretty much iterated until it stopped |
Cool, this is probably good to merge as-is, then! Thanks again! |
# 0.1.26 (April 14, 2022) This release adds a `Value` implementation for `Box<T: Value>` to allow recording boxed values more conveniently. In particular, this should improve the ergonomics of the implementations for `dyn std::error::Error` trait objects, including those added in [v0.1.25]. ### Added - `Value` implementation for `Box<T> where T: Value` ([#2071]) ### Fixed - Broken documentation links ([#2068]) Thanks to new contributor @ben0x539 for contributing to this release! [v0.1.25]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.25 [#2071]: #2071 [#2068]: #2068
# 0.1.34 (April 14, 2022) This release includes bug fixes for the "log" support feature and for the use of both scoped and global default dispatchers in the same program. ### Fixed - Failure to use the global default dispatcher when a thread sets a local default dispatcher before the global default is set ([#2065]) - **log**: Compilation errors due to `async` block/fn futures becoming `!Send` when the "log" feature flag is enabled ([#2073]) - Broken links in documentation ([#2068]) Thanks to @ben0x539 for contributing to this release! [#2065]: #2065 [#2073]: #2073 [#2068]: #2068
# 0.1.34 (April 14, 2022) This release includes bug fixes for the "log" support feature and for the use of both scoped and global default dispatchers in the same program. ### Fixed - Failure to use the global default dispatcher when a thread sets a local default dispatcher before the global default is set ([#2065]) - **log**: Compilation errors due to `async` block/fn futures becoming `!Send` when the "log" feature flag is enabled ([#2073]) - Broken links in documentation ([#2068]) Thanks to @ben0x539 for contributing to this release! [#2065]: #2065 [#2073]: #2073 [#2068]: #2068
# 0.1.34 (April 14, 2022) This release includes bug fixes for the "log" support feature and for the use of both scoped and global default dispatchers in the same program. ### Fixed - Failure to use the global default dispatcher when a thread sets a local default dispatcher before the global default is set ([#2065]) - **log**: Compilation errors due to `async` block/fn futures becoming `!Send` when the "log" feature flag is enabled ([#2073]) - Broken links in documentation ([#2068]) Thanks to @ben0x539 for contributing to this release! [#2065]: #2065 [#2073]: #2073 [#2068]: #2068
# 0.1.3 (April 21st, 2022) ### Added - **log-tracer**: Added `LogTracer::with_interest_cache` to enable a limited form of per-record `Interest` caching for `log` records ([#1636]) ### Changed - Updated minimum supported Rust version (MSRV) to Rust 1.49.0 ([#1913]) ### Fixed - **log-tracer**: Fixed `LogTracer` not honoring `tracing` max level filters ([#1543]) - Broken links in documentation ([#2068], [#2077]) Thanks to @Millione, @teozkr, @koute, @Folyd, and @ben0x539 for contributing to this release! [#1636]: https://github.com/tokio-rs/tracing/pulls/1636 [#1913]: https://github.com/tokio-rs/tracing/pulls/1913 [#1543]: https://github.com/tokio-rs/tracing/pulls/1543 [#2068]: https://github.com/tokio-rs/tracing/pulls/2068 [#2077]: https://github.com/tokio-rs/tracing/pulls/2077
# 0.1.3 (April 21st, 2022) ### Added - **log-tracer**: Added `LogTracer::with_interest_cache` to enable a limited form of per-record `Interest` caching for `log` records ([#1636]) ### Changed - Updated minimum supported Rust version (MSRV) to Rust 1.49.0 ([#1913]) ### Fixed - **log-tracer**: Fixed `LogTracer` not honoring `tracing` max level filters ([#1543]) - Broken links in documentation ([#2068], [#2077]) Thanks to @Millione, @teozkr, @koute, @Folyd, and @ben0x539 for contributing to this release! [#1636]: https://github.com/tokio-rs/tracing/pulls/1636 [#1913]: https://github.com/tokio-rs/tracing/pulls/1913 [#1543]: https://github.com/tokio-rs/tracing/pulls/1543 [#2068]: https://github.com/tokio-rs/tracing/pulls/2068 [#2077]: https://github.com/tokio-rs/tracing/pulls/2077 Fixes #1884 Fixes #1664
# 0.1.21 (April 26, 2022) This release adds support for setting explicit parent and follows-from spans in the `#[instrument]` attribute. ### Added - `#[instrument(follows_from = ...)]` argument for setting one or more follows-from span ([#2093]) - `#[instrument(parent = ...)]` argument for overriding the generated span's parent ([#2091]) ### Fixed - Extra braces around `async` blocks in expanded code (causes a Clippy warning) ([#2090]) - Broken documentation links ([#2068], [#2077]) Thanks to @jarrodldavis, @ben0x539, and new contributor @jswrenn for contributing to this release! [#2093]: #2093 [#2091]: #2091 [#2090]: #2090 [#2077]: #2077 [#2068]: #2068
# 0.1.21 (April 26, 2022) This release adds support for setting explicit parent and follows-from spans in the `#[instrument]` attribute. ### Added - `#[instrument(follows_from = ...)]` argument for setting one or more follows-from span ([#2093]) - `#[instrument(parent = ...)]` argument for overriding the generated span's parent ([#2091]) ### Fixed - Extra braces around `async` blocks in expanded code (causes a Clippy warning) ([#2090]) - Broken documentation links ([#2068], [#2077]) Thanks to @jarrodldavis, @ben0x539, and new contributor @jswrenn for contributing to this release! [#2093]: #2093 [#2091]: #2091 [#2090]: #2090 [#2077]: #2077 [#2068]: #2068
# 0.3.12 (Jun 29, 2022) This release of `tracing-subscriber` adds a new `Layer::event_enabled` method, which allows `Layer`s to filter events *after* their field values are recorded; a `Filter` implementation for `reload::Layer`, to make using `reload` with per-layer filtering more ergonomic, and additional inherent method downcasting APIs for the `Layered` type. In addition, it includes dependency updates, and minor fixes for documentation and feature flagging. ### Added - **layer**: `Layer::event_enabled` method, which can be implemented to filter events based on their field values (#2008) - **reload**: `Filter` implementation for `reload::Layer` (#2159) - **layer**: `Layered::downcast_ref` and `Layered::is` inherent methods (#2160) ### Changed - **parking_lot**: Updated dependency on `parking_lot` to 0.13.0 (#2143) - Replaced `lazy_static` dependency with `once_cell` (#2147) ### Fixed - Don't enable `tracing-core` features by default (#2107) - Several documentation link and typo fixes (#2064, #2068, #2077, #2161, #1088) Thanks to @ben0x539, @jamesmunns, @georgemp, @james7132, @jswrenn, @CAD97, and @guswynn for contributing to this release!
# 0.3.12 (Jun 29, 2022) This release of `tracing-subscriber` adds a new `Layer::event_enabled` method, which allows `Layer`s to filter events *after* their field values are recorded; a `Filter` implementation for `reload::Layer`, to make using `reload` with per-layer filtering more ergonomic, and additional inherent method downcasting APIs for the `Layered` type. In addition, it includes dependency updates, and minor fixes for documentation and feature flagging. ### Added - **layer**: `Layer::event_enabled` method, which can be implemented to filter events based on their field values (#2008) - **reload**: `Filter` implementation for `reload::Layer` (#2159) - **layer**: `Layered::downcast_ref` and `Layered::is` inherent methods (#2160) ### Changed - **parking_lot**: Updated dependency on `parking_lot` to 0.13.0 (#2143) - Replaced `lazy_static` dependency with `once_cell` (#2147) ### Fixed - Don't enable `tracing-core` features by default (#2107) - Several documentation link and typo fixes (#2064, #2068, #2077, #2161, #1088) Thanks to @ben0x539, @jamesmunns, @georgemp, @james7132, @jswrenn, @CAD97, and @guswynn for contributing to this release!
eventually realized it's because a lot of stuff is reexported in parent modules and so the file path based relative links couldn't possibly work in all contexts. Looks like master already underwent this treatment but I suspect this is easier than backporting. Intra-doc links seem pretty good. I started with ``` find -name \*.rs -exec sed -i -e ' s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\w\+\.\(\w\+\)\.html@\1super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\w\+\.\(\w\+\)\.html@\1super::super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::super::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/index\.html@\1super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./index\.html@\1super@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\?$@\1super::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\w\+\.\(\w\+\)\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/index\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./index\.html@\1self@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\?$@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\w\+\.\(\w\+\)\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/index\.html@\1self::\2@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?index\.html@\1self@; s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\?$@\1self::\2@; s@\(//. \[[^]]*\]:\s\+[A-Za-z_0-9:]\+\)#method\.\(\w\+\)@\1::\2@; ' {} + ``` and then removed redundant `self::`s when I realized you don't actually need a `::` in the links, and fixed stuff up by hand as I ran into errors from ``` x='--cfg docsrs --cfg tracing_unstable'; RUSTFLAGS=$x RUSTDOCFLAGS=$x cargo doc --all-features ``` I hope that's roughly how the docs are supposed to work. I understand this is a relatively big unsolicited change in that it touches a whole lot of files (definitely went further than I originally intended), I'm happy to revise or split or reduce scope of this PR as desired.
# 0.1.26 (April 14, 2022) This release adds a `Value` implementation for `Box<T: Value>` to allow recording boxed values more conveniently. In particular, this should improve the ergonomics of the implementations for `dyn std::error::Error` trait objects, including those added in [v0.1.25]. ### Added - `Value` implementation for `Box<T> where T: Value` ([tokio-rs#2071]) ### Fixed - Broken documentation links ([tokio-rs#2068]) Thanks to new contributor @ben0x539 for contributing to this release! [v0.1.25]: https://github.com/tokio-rs/tracing/releases/tag/tracing-core-0.1.25 [tokio-rs#2071]: tokio-rs#2071 [tokio-rs#2068]: tokio-rs#2068
# 0.1.34 (April 14, 2022) This release includes bug fixes for the "log" support feature and for the use of both scoped and global default dispatchers in the same program. ### Fixed - Failure to use the global default dispatcher when a thread sets a local default dispatcher before the global default is set ([tokio-rs#2065]) - **log**: Compilation errors due to `async` block/fn futures becoming `!Send` when the "log" feature flag is enabled ([tokio-rs#2073]) - Broken links in documentation ([tokio-rs#2068]) Thanks to @ben0x539 for contributing to this release! [tokio-rs#2065]: tokio-rs#2065 [tokio-rs#2073]: tokio-rs#2073 [tokio-rs#2068]: tokio-rs#2068
# 0.1.3 (April 21st, 2022) ### Added - **log-tracer**: Added `LogTracer::with_interest_cache` to enable a limited form of per-record `Interest` caching for `log` records ([tokio-rs#1636]) ### Changed - Updated minimum supported Rust version (MSRV) to Rust 1.49.0 ([tokio-rs#1913]) ### Fixed - **log-tracer**: Fixed `LogTracer` not honoring `tracing` max level filters ([tokio-rs#1543]) - Broken links in documentation ([tokio-rs#2068], [tokio-rs#2077]) Thanks to @Millione, @teozkr, @koute, @Folyd, and @ben0x539 for contributing to this release! [tokio-rs#1636]: https://github.com/tokio-rs/tracing/pulls/1636 [tokio-rs#1913]: https://github.com/tokio-rs/tracing/pulls/1913 [tokio-rs#1543]: https://github.com/tokio-rs/tracing/pulls/1543 [tokio-rs#2068]: https://github.com/tokio-rs/tracing/pulls/2068 [tokio-rs#2077]: https://github.com/tokio-rs/tracing/pulls/2077 Fixes tokio-rs#1884 Fixes tokio-rs#1664
# 0.1.21 (April 26, 2022) This release adds support for setting explicit parent and follows-from spans in the `#[instrument]` attribute. ### Added - `#[instrument(follows_from = ...)]` argument for setting one or more follows-from span ([tokio-rs#2093]) - `#[instrument(parent = ...)]` argument for overriding the generated span's parent ([tokio-rs#2091]) ### Fixed - Extra braces around `async` blocks in expanded code (causes a Clippy warning) ([tokio-rs#2090]) - Broken documentation links ([tokio-rs#2068], [tokio-rs#2077]) Thanks to @jarrodldavis, @ben0x539, and new contributor @jswrenn for contributing to this release! [tokio-rs#2093]: tokio-rs#2093 [tokio-rs#2091]: tokio-rs#2091 [tokio-rs#2090]: tokio-rs#2090 [tokio-rs#2077]: tokio-rs#2077 [tokio-rs#2068]: tokio-rs#2068
# 0.3.12 (Jun 29, 2022) This release of `tracing-subscriber` adds a new `Layer::event_enabled` method, which allows `Layer`s to filter events *after* their field values are recorded; a `Filter` implementation for `reload::Layer`, to make using `reload` with per-layer filtering more ergonomic, and additional inherent method downcasting APIs for the `Layered` type. In addition, it includes dependency updates, and minor fixes for documentation and feature flagging. ### Added - **layer**: `Layer::event_enabled` method, which can be implemented to filter events based on their field values (tokio-rs#2008) - **reload**: `Filter` implementation for `reload::Layer` (tokio-rs#2159) - **layer**: `Layered::downcast_ref` and `Layered::is` inherent methods (tokio-rs#2160) ### Changed - **parking_lot**: Updated dependency on `parking_lot` to 0.13.0 (tokio-rs#2143) - Replaced `lazy_static` dependency with `once_cell` (tokio-rs#2147) ### Fixed - Don't enable `tracing-core` features by default (tokio-rs#2107) - Several documentation link and typo fixes (tokio-rs#2064, tokio-rs#2068, tokio-rs#2077, tokio-rs#2161, tokio-rs#1088) Thanks to @ben0x539, @jamesmunns, @georgemp, @james7132, @jswrenn, @CAD97, and @guswynn for contributing to this release!
# 0.2.1 (November 28, 2024) [ [crates.io][crate-0.2.1] ] | [ [docs.rs][docs-0.2.1] ] ### Changed - Bump MSRV to 1.63 ([#2793]) ### Documented - Use intra-doc links instead of relative file paths ([#2068]) - More intra-doc links ([#2077]) - Add missing backtick to `prelude` docs ([#2120]) [#2068]: #2068 [#2077]: #2077 [#2120]: #2120 [#2793]: #2793 [docs-0.2.1]: https://docs.rs/tracing-error/0.2.1/tracing_error/ [crate-0.2.1]: https://crates.io/crates/tracing-error/0.2.1
# 0.2.1 (November 29, 2024) [ [crates.io][crate-0.2.1] ] | [ [docs.rs][docs-0.2.1] ] ### Changed - Bump MSRV to 1.63 ([#2793]) ### Documented - Use intra-doc links instead of relative file paths ([#2068]) - More intra-doc links ([#2077]) - Add missing backtick to `prelude` docs ([#2120]) [#2068]: #2068 [#2077]: #2077 [#2120]: #2120 [#2793]: #2793 [docs-0.2.1]: https://docs.rs/tracing-error/0.2.1/tracing_error/ [crate-0.2.1]: https://crates.io/crates/tracing-error/0.2.1
# 0.2.1 (November 29, 2024) [ [crates.io][crate-0.2.1] ] | [ [docs.rs][docs-0.2.1] ] ### Changed - Bump MSRV to 1.63 ([#2793]) ### Documented - Use intra-doc links instead of relative file paths ([#2068]) - More intra-doc links ([#2077]) - Add missing backtick to `prelude` docs ([#2120]) [#2068]: #2068 [#2077]: #2077 [#2120]: #2120 [#2793]: #2793 [docs-0.2.1]: https://docs.rs/tracing-error/0.2.1/tracing_error/ [crate-0.2.1]: https://crates.io/crates/tracing-error/0.2.1
Motivation
#940, I guess. I kept running into the odd broken link in the docs and eventually realized it's because a lot of stuff is reexported in parent modules and so the file path based relative links couldn't possibly work in all contexts. Looks like master already underwent this treatment but I suspect this is easier than backporting.
Solution
Intra-doc links seem pretty good.
I started with
and then removed redundant
self::
s when I realized you don't actually need a::
in the links, and fixed stuff up by hand as I ran into errors fromI hope that's roughly how the docs are supposed to work.
I understand this is a relatively big unsolicited change in that it touches a whole lot of files (definitely went further than I originally intended), I'm happy to revise or split or reduce scope of this PR as desired.