mock: add README to tracing-mock #2362
Conversation
There has been interest around publishing `tracing-mock` to crates.io for some time. In order to make this possible, documentation and some code clean up is needed. This change starts that process by adding a README for `tracing-mock`. The README follows the standard format for all `tracing` crates and includes 2 examples. Additionally an integration test has been added for each example. The README describes steps when using the `tracing` 1.0 from crates.io and `tracing-mock` from the `v0.1.x` branch. The tests target the current branch. Refs: #539
hds
changed the title
hds
changed the title
Suggestions from @davidbarsky Co-authored-by: David Barsky <me@davidbarsky.com>
Suggestions from @davidbarsky Co-authored-by: David Barsky <me@davidbarsky.com>
Suggestions from @davidbarsky Co-authored-by: David Barsky <me@davidbarsky.com>
Suggestion from @davidbarsky Co-authored-by: David Barsky <me@davidbarsky.com>
The readme.rs test file has been removed, since the tests from the README for `tracing-mock` will get run as part of the doc test. Necessarily, the examples in the README now target the master branch, and not the `v0.1.x` branch.
There was a problem hiding this comment.
Overall, this looks great. The one real blocker is that the docs build is currently failing due to the relative link to the LICENSE file, which is no longer valid when the README is included in the RustDoc. If we make that an absolute link, I'll be happy to merge this!
I also commented on a few other nits, but they're not blockers.
Suggestion from @hawkw Co-authored-by: Eliza Weisman <eliza@buoyant.io>
- Fixed the link to the license (so it's absolute) - Link to tracing docs when describing what tracing-mock does - Fixed the test crate version example - Removed reference to removed test file (no longer needed)
|
now that #2377 has merged, the examples here will need to be updated to match the new APIs. |
|
~~looks like the most recent docs build CI failures are due to an issue with our netlify config, rather than something in the new docs: https://app.netlify.com/sites/tracing-rs/deploys/636a9cac2ea34100084c2ad4 i'm gonna try to get that fixed~~ edit: actually, never mind, looks like there's link breakage as well: https://app.netlify.com/sites/tracing-rs/deploys/636e8c854b113a0008951581#L249 |
tracing-mock/README.md
Outdated
| [`Collector`](https://tracing-rs.netlify.app/tracing/#collectors) | ||
| that allows asserting on the order and contents of | ||
| [spans]https://tracing-rs.netlify.app/tracing/#spans) and | ||
| [events](https://tracing-rs.netlify.app/tracing/#events). |
There was a problem hiding this comment.
rather than linking to the netlify master docs here, i think we should probably be linking to the release docs on docs.rs, at least in the release version of these docs...we can change them to point to docs.rs when we do the v0.1.x backport, if you think having this version of the documentation point at the v0.2.x documentation for tracing, but it's a thing we'll need to remember...
There was a problem hiding this comment.
My idea was to link to both the docs.rs docs and the master docs once we publish on crates.io, as that's what is done in the other crates in this repo. Since we don't have the docs.rs ones yet, I left it out entirely.
Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Also changed `.done()` to `.only()` and remove `.close_span()` entirely because it's not actually implemented yet.
There has been interest around publishing `tracing-mock` to crates.io for some time. In order to make this possible, documentation and some code clean up is needed. Specifically **I** want to have access to `tracing-mock` within parts of `tokio` to write tests that ensure that the correct calling location is picked up for all `spawn*` functions when the `tracing` feature is enabled. This change starts that process by adding a README for `tracing-mock`. The README follows the standard format for all `tracing` crates and includes 2 examples. The README is included in the `lib.rs` docs using `#[doc = include_str!(...)]`, so that the same documentation is included in the crate, and the examples are tested when running doctests. The README describes steps when using the `tracing` 1.0 from crates.io and `tracing-mock` from the `v0.1.x` branch. The tests target the current branch. Co-authored-by: David Barsky <me@davidbarsky.com> Co-authored-by: Eliza Weisman <eliza@buoyant.io>
There has been interest around publishing `tracing-mock` to crates.io for some time. In order to make this possible, documentation and some code clean up is needed. Specifically **I** want to have access to `tracing-mock` within parts of `tokio` to write tests that ensure that the correct calling location is picked up for all `spawn*` functions when the `tracing` feature is enabled. This change starts that process by adding a README for `tracing-mock`. The README follows the standard format for all `tracing` crates and includes 2 examples. The README is included in the `lib.rs` docs using `#[doc = include_str!(...)]`, so that the same documentation is included in the crate, and the examples are tested when running doctests. The README describes steps when using the `tracing` 1.0 from crates.io and `tracing-mock` from the `v0.1.x` branch. The tests target the current branch. Co-authored-by: David Barsky <me@davidbarsky.com> Co-authored-by: Eliza Weisman <eliza@buoyant.io>
Motivation
There has been interest around publishing
tracing-mockto crates.io for some time. In order to make this possible, documentation and some code clean up is needed.Specifically I want to have access to
tracing-mockwithin parts oftokioto write tests that ensure that the correct calling location is picked up for allspawn*functions when thetracingfeature is enabled.Solution
This change starts that process by adding a README for
tracing-mock. The README follows the standard format for alltracingcrates and includes 2 examples. Additionally an integration test has been added for each example.The README describes steps when using the
tracing1.0 from crates.io andtracing-mockfrom thev0.1.xbranch. The tests target the current branch.