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 |
hawkw
left a comment
There was a problem hiding this comment.
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.
| //! | ||
| //! [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.
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.
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.