Merge pull request #143 from joshka/jm/docs-tracing

docs: document tracing support in README and lib.rs

Author: epage

README.md

@@ -1,4 +1,4 @@
-# clap-verbosity-flag for `log`
+# clap-verbosity-flag for `log` / `tracing`
 
 [![Documentation](https://img.shields.io/badge/docs-master-blue.svg)][Documentation]
 ![License](https://img.shields.io/crates/l/clap-verbosity-flag.svg)
@@ -7,27 +7,65 @@
 [Crates.io]: https://crates.io/crates/clap-verbosity-flag
 [Documentation]: https://docs.rs/clap-verbosity-flag/
 
-Easily add a `--verbose` flag to CLIs using Clap
+Easily add `--verbose` and `--quiet` flags to CLIs using [Clap](http://crates.io/crates/clap).
 
 ## Examples
 
+```shell
+cargo add clap-verbosity-flag
+```
+
 ```rust
 use clap::Parser;
 
-// ...
 #[derive(Debug, Parser)]
 struct Cli {
     #[command(flatten)]
-    verbose: clap_verbosity_flag::Verbosity,
+    verbosity: clap_verbosity_flag::Verbosity,
 }
+
+fn main() {
+    let args = Cli::parse();
+    env_logger::Builder::new()
+        .filter_level(args.verbosity.into())
+        .init();
+    // Your code here
+}
+```
+
+For [`tracing`](https://crates.io/crates/tracing) support, use the `tracing` feature:
+
+```shell
+cargo add clap-verbosity-flag --no-default-features --features tracing
 ```
 
-By default, it'll only report errors.
-- `-q` silences output
-- `-v` show warnings
-- `-vv` show info
-- `-vvv` show debug
-- `-vvvv` show trace
+```rust
+use clap::Parser;
+
+#[derive(Debug, Parser)]
+struct Cli {
+    #[command(flatten)]
+    verbosity: clap_verbosity_flag::Verbosity,
+}
+
+fn main() {
+    let args = Cli::parse();
+    tracing_subscriber::fmt()
+        .with_max_level(args.verbosity)
+        .init();
+    // Your code here
+}
+```
+
+The default verbosity level will cause `log` / `tracing` to only report errors. The flags can be
+specified multiple times to increase or decrease the verbosity level. See the [Documentation] for
+info on how to change the default verbosity level.
+
+- silence output: `-q` / `--quiet`
+- show warnings: `-v` / `--verbose`
+- show info: `-vv` / `--verbose --verbose`
+- show debug: `-vvv` / `--verbose --verbose --verbose`
+- show trace: `-vvvv` / `--verbose --verbose --verbose --verbose`
 
 ## License
 

src/lib.rs

@@ -1,45 +1,80 @@
-//! Control `log` level with a `--verbose` flag for your CLI
+//! Easily add `--verbose` and `--quiet` flags to CLIs using [Clap](http://crates.io/crates/clap).
 //!
 //! # Examples
 //!
 //! To get `--quiet` and `--verbose` flags through your entire program, just `flatten`
 //! [`Verbosity`]:
+//!
+//! ```rust,no_run
+//! use clap::Parser;
+//! use clap_verbosity_flag::Verbosity;
+//!
+//! #[derive(Debug, Parser)]
+//! struct Cli {
+//!     #[command(flatten)]
+//!     verbosity: Verbosity,
+//!
+//!     // ... other options
+//! }
+//! ```
+//!
+//! You can then use this to configure your logger:
+//!
 //! ```rust,no_run
 //! # use clap::Parser;
 //! # use clap_verbosity_flag::Verbosity;
 //! #
-//! # /// Le CLI
 //! # #[derive(Debug, Parser)]
 //! # struct Cli {
-//! #[command(flatten)]
-//! verbose: Verbosity,
+//! #     #[command(flatten)]
+//! #     verbosity: Verbosity,
 //! # }
+//! let cli = Cli::parse();
+//! # #[cfg(feature = "log")]
+//! env_logger::Builder::new()
+//!     .filter_level(cli.verbosity.log_level_filter())
+//!     .init();
 //! ```
 //!
-//! You can then use this to configure your logger:
+//! ## Use with `tracing`
+//!
+//! To use with [`tracing`](https://crates.io/crates/tracing), disable the log feature flag and
+//! enable the `tracing` feature flag:
+//!
+//! ```shell
+//! cargo add clap_verbosity_flag --no-default features --features tracing
+//! ```
+//!
+//! Then you can use it like this:
+//!
 //! ```rust,no_run
 //! # use clap::Parser;
 //! # use clap_verbosity_flag::Verbosity;
 //! #
-//! # /// Le CLI
 //! # #[derive(Debug, Parser)]
 //! # struct Cli {
 //! #     #[command(flatten)]
-//! #     verbose: Verbosity,
+//! #     verbosity: Verbosity,
 //! # }
 //! let cli = Cli::parse();
-//! # #[cfg(feature = "log")]
-//! env_logger::Builder::new()
-//!     .filter_level(cli.verbose.log_level_filter())
+//! # #[cfg(feature = "tracing")]
+//! tracing_subscriber::fmt()
+//!     .with_max_level(cli.verbosity)
 //!     .init();
 //! ```
 //!
-//! By default, this will only report errors.
-//! - `-q` silences output
-//! - `-v` show warnings
-//! - `-vv` show info
-//! - `-vvv` show debug
-//! - `-vvvv` show trace
+//! # Using `--verbose` and `--quiet` flags
+//!
+//! The default verbosity level will cause `log` / `tracing` to only report errors. The flags can be
+//!  specified multiple times to increase or decrease the verbosity level.
+//!
+//! - silence output: `-q` / `--quiet`
+//! - show warnings: `-v` / `--verbose`
+//! - show info: `-vv` / `--verbose --verbose`
+//! - show debug: `-vvv` / `--verbose --verbose --verbose`
+//! - show trace: `-vvvv` / `--verbose --verbose --verbose --verbose`
+//!
+//! # Customizing the default log level
 //!
 //! By default, the log level is set to Error. To customize this to a different level, pass a type
 //! implementing the [`LogLevel`] trait to [`Verbosity`]:
@@ -48,7 +83,6 @@
 //! # use clap::Parser;
 //! use clap_verbosity_flag::{Verbosity, InfoLevel};
 //!
-//! /// Le CLI
 //! #[derive(Debug, Parser)]
 //! struct Cli {
 //!     #[command(flatten)]
@@ -63,7 +97,7 @@
 #![warn(clippy::print_stdout)]
 
 #[doc = include_str!("../README.md")]
-#[cfg(doctest)]
+#[cfg(all(doctest, feature = "log", feature = "tracing"))]
 pub struct ReadmeDoctests;
 
 use std::fmt;