-
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
docs: more intra-doc links #2077
Merged
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
... also it deleted some redundant ones, and it got some things wrong, and it was gonna delete some of the cross-crate docs.rs links we can't do as intra-doc links so I passed `--no-favored`.
Note that this adds some more broken intra doc links when building without std support, but that was already a thing and I expect people who build their own docs without std support can handle it. This time I gave up on sed and used ruby. find -name '*.rs' -exec ruby -i -p blah.rb {} + with $_.gsub!(%r{ https://doc\.rust-lang\.org/ (?: stable/)? ((?:core | std | alloc)(?:/\S+?)*) /(\w+)\.(\w+)\.html}x ) { path, kind, name = $~.captures suffix = case kind when 'method' then '()' when 'macro' then '!' else '' end r = [path.gsub('/', '::'), '::', name, suffix].join STDERR.puts [path, kind, name, suffix, r].inspect r } $_.gsub!(%r{ https://doc\.rust-lang\.org/ (?: stable/)? ((?: core | std | alloc)(?:/\S+?)*) /(?: index\.html | $ | (?= \#) )}x ) { path, _ = $~.captures r = path.gsub('/', '::') STDERR.puts [path, r].inspect r }
cargo intraconv doesn't seem to get them reliably and also plenty of links to other crates aren't actually intra-doc because they're in crates that don't depend (or only dev-depend, or only conditionally depend) on those crates, so this wasn't very automated. I tried to only convert docs.rs links to unconditional dependencies to intra-crate links, but it's possible that some slipped through in either direction.
ben0x539
requested review from
a team,
jtescher,
yaahc and
hawkw
as code owners
April 15, 2022 02:13
hawkw
approved these changes
Apr 19, 2022
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.
Provided the docs build successfully (which the CI results indicate they do), this looks great to me! Thanks for your continued work on this!
hawkw
added a commit
that referenced
this pull request
Apr 21, 2022
# 0.3.0 (April 21, 2022) This is a breaking release which changes the format in which span fields are output to `journald`. Previously, span field names were prefixed with the depth of the span in the current trace tree. However, these prefixes are unnecessary, as `journald` has built in support for duplicated field names. See PR [#1986] for details on this change. ## Changed - Removed span field prefixes ([#1986]) - Renamed `S{num}_NAME` fields to `SPAN_NAME ([#1986]) ### Fixed - Fixed broken links in documentation ([#2077]) Thanks to @wiktorsikora and @ben0x539 for contributing to this release! [#1986]: #1986 [#2077]: #2077
hawkw
added a commit
that referenced
this pull request
Apr 21, 2022
# 0.3.0 (April 21, 2022) This is a breaking release which changes the format in which span fields are output to `journald`. Previously, span field names were prefixed with the depth of the span in the current trace tree. However, these prefixes are unnecessary, as `journald` has built in support for duplicated field names. See PR [#1986] for details on this change. ## Changed - Removed span field prefixes ([#1986]) - Renamed `S{num}_NAME` fields to `SPAN_NAME ([#1986]) ### Fixed - Fixed broken links in documentation ([#2077]) Thanks to @wiktorsikora and @ben0x539 for contributing to this release! [#1986]: #1986 [#2077]: #2077
hawkw
added a commit
that referenced
this pull request
Apr 21, 2022
# 0.3.0 (April 21, 2022) This is a breaking release which changes the format in which span fields are output to `journald`. Previously, span field names were prefixed with the depth of the span in the current trace tree. However, these prefixes are unnecessary, as `journald` has built in support for duplicated field names. See PR [#1986] for details on this change. ## Changed - Removed span field prefixes ([#1986]) - Renamed `S{num}_NAME` fields to `SPAN_NAME ([#1986]) ### Fixed - Fixed broken links in documentation ([#2077]) Thanks to @wiktorsikora and @ben0x539 for contributing to this release! [#1986]: #1986 [#2077]: #2077
hawkw
added a commit
that referenced
this pull request
Apr 21, 2022
# 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
hawkw
added a commit
that referenced
this pull request
Apr 21, 2022
# 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
hawkw
added a commit
that referenced
this pull request
Apr 26, 2022
# 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
hawkw
added a commit
that referenced
this pull request
Apr 27, 2022
# 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
hawkw
added a commit
that referenced
this pull request
Jun 29, 2022
# 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!
hawkw
added a commit
that referenced
this pull request
Jun 29, 2022
# 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!
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
* docs: `cargo intraconv` for more intra-doc links ... also it deleted some redundant ones, and it got some things wrong, and it was gonna delete some of the cross-crate docs.rs links we can't do as intra-doc links so I passed `--no-favored`. * docs: convert https:// links to std/core/alloc to intra-doc links Note that this adds some more broken intra doc links when building without std support, but that was already a thing and I expect people who build their own docs without std support can handle it. This time I gave up on sed and used ruby. find -name '*.rs' -exec ruby -i -p blah.rb {} + with $_.gsub!(%r{ https://doc\.rust-lang\.org/ (?: stable/)? ((?:core | std | alloc)(?:/\S+?)*) /(\w+)\.(\w+)\.html}x ) { path, kind, name = $~.captures suffix = case kind when 'method' then '()' when 'macro' then '!' else '' end r = [path.gsub('/', '::'), '::', name, suffix].join STDERR.puts [path, kind, name, suffix, r].inspect r } $_.gsub!(%r{ https://doc\.rust-lang\.org/ (?: stable/)? ((?: core | std | alloc)(?:/\S+?)*) /(?: index\.html | $ | (?= \#) )}x ) { path, _ = $~.captures r = path.gsub('/', '::') STDERR.puts [path, r].inspect r } * docs: more cross-crate intra-doc links cargo intraconv doesn't seem to get them reliably and also plenty of links to other crates aren't actually intra-doc because they're in crates that don't depend (or only dev-depend, or only conditionally depend) on those crates, so this wasn't very automated. I tried to only convert docs.rs links to unconditional dependencies to intra-crate links, but it's possible that some slipped through in either direction.
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
# 0.3.0 (April 21, 2022) This is a breaking release which changes the format in which span fields are output to `journald`. Previously, span field names were prefixed with the depth of the span in the current trace tree. However, these prefixes are unnecessary, as `journald` has built in support for duplicated field names. See PR [tokio-rs#1986] for details on this change. ## Changed - Removed span field prefixes ([tokio-rs#1986]) - Renamed `S{num}_NAME` fields to `SPAN_NAME ([tokio-rs#1986]) ### Fixed - Fixed broken links in documentation ([tokio-rs#2077]) Thanks to @wiktorsikora and @ben0x539 for contributing to this release! [tokio-rs#1986]: tokio-rs#1986 [tokio-rs#2077]: tokio-rs#2077
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
# 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
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
# 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
kaffarell
pushed a commit
to kaffarell/tracing
that referenced
this pull request
May 22, 2024
# 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!
hds
added a commit
that referenced
this pull request
Nov 28, 2024
# 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
hds
added a commit
that referenced
this pull request
Nov 29, 2024
# 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
hds
added a commit
that referenced
this pull request
Nov 29, 2024
# 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Intra-doc links are neat and get checked by rustdoc. #940.
Solution
Continuing from #2068, this changes more links in doc comments from full URLs to intra-doc links and cleans up some redundant
[`Foo`]: Foo
-style links, partly with the help ofcargo intraconv
which I've since been pointed at.Primarily,
#foo
links turned intoBlah::foo
std
etcFor the latter I've tried to be conservative so that people who build their own docs with some features disabled don't get broken links (but possibly missed some since this was kinda manual, and there were already warnings for unresolved references without some features). For
std
I have not been conservative even thoughstd
is optional in places as there were already a bunch of intra-doc links tostd
.