docs: more intra-doc links #2077
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
hawkw
approved these changes
Apr 19, 2022
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 intraconvwhich I've since been pointed at.Primarily,
#foolinks turned intoBlah::foostdetcFor 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
stdI have not been conservative even thoughstdis optional in places as there were already a bunch of intra-doc links tostd.