Merge pull request #310 from epage/docs

docs: Talk abotu new styling API

Author: epage

CHANGELOG.md

@@ -15,6 +15,21 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [0.11.0] - 2024-01-19
 
+### Migration Guide
+
+**env_logger::fmt::Style:**
+The bespoke styling API, behind `color`, was removed, in favor of accepting any
+ANSI styled string and adapting it to the target stream's capabilities.
+
+Possible styling libraries include:
+- [anstyle](https://docs.rs/anstyle) is a minimal, runtime string styling API and is re-exported as `env_logger::fmt::style`
+- [owo-colors](https://docs.rs/owo-colors) is a feature rich runtime string styling API
+- [color-print](https://docs.rs/color-print) for feature-rich compile-time styling API
+
+[custom_format.rs](https://docs.rs/env_logger/latest/src/custom_format/custom_format.rs.html)
+uses `anstyle` via
+[`Formatter::default_level_style`](https://docs.rs/env_logger/latest/env_logger/fmt/struct.Formatter.html#method.default_level_style)
+
 ### Breaking Change
 
 - Removed bespoke styling API

Cargo.lock

@@ -58,7 +58,7 @@ log = { version = "0.4.8", features = ["std"] }
 env_filter = { version = "0.1.0", path = "crates/env_filter", default-features = false }
 humantime = { version = "2.0.0", optional = true }
 anstream = { version = "0.6.11", default-features = false, features = ["wincon"], optional = true }
-anstyle = { version = "1.0.4", optional = true }
+anstyle = { version = "1.0.6", optional = true }
 
 [[test]]
 name = "regexp_filter"

Cargo.toml

@@ -33,13 +33,11 @@ fn main() {
                 // We are reusing `anstyle` but there are `anstyle-*` crates to adapt it to your
                 // preferred styling crate.
                 let warn_style = buf.default_level_style(log::Level::Warn);
-                let reset = warn_style.render_reset();
-                let warn_style = warn_style.render();
                 let timestamp = buf.timestamp();
 
                 writeln!(
                     buf,
-                    "My formatted log ({timestamp}): {warn_style}{}{reset}",
+                    "My formatted log ({timestamp}): {warn_style}{}{warn_style:#}",
                     record.args()
                 )
             })

examples/custom_format.rs

@@ -25,8 +25,6 @@ impl Formatter {
     ///     writeln!(buf, "{}: {}: {}", ts, record.level(), record.args())
     /// });
     /// ```
-    ///
-    /// [`Timestamp`]: struct.Timestamp.html
     pub fn timestamp(&self) -> Timestamp {
         Timestamp {
             time: SystemTime::now(),
@@ -76,8 +74,7 @@ impl Formatter {
 /// The timestamp implements [`Display`] and can be written to a [`Formatter`].
 ///
 /// [RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
-/// [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
-/// [`Formatter`]: struct.Formatter.html
+/// [`Display`]: std::fmt::Display
 pub struct Timestamp {
     time: SystemTime,
     precision: TimestampPrecision,

src/fmt/humantime.rs

@@ -9,8 +9,14 @@
 //!
 //! The format used to print log records can be customised using the [`Builder::format`]
 //! method.
-//! Custom formats can apply different color and weight to printed values using
-//! [`Style`] builders.
+//!
+//! Terminal styling is done through ANSI escape codes and will be adapted to the capabilities of
+//! the target stream.
+//! For example, you could use one of:
+//! - [anstyle](https://docs.rs/anstyle) is a minimal, runtime string styling API and is re-exported as [`style`]
+//! - [owo-colors](https://docs.rs/owo-colors) is a feature rich runtime string styling API
+//! - [color-print](https://docs.rs/color-print) for feature-rich compile-time styling API
+//! See also [`Formatter::default_level_style`]
 //!
 //! ```
 //! use std::io::Write;
@@ -24,10 +30,8 @@
 //! });
 //! ```
 //!
-//! [`Formatter`]: struct.Formatter.html
-//! [`Style`]: struct.Style.html
-//! [`Builder::format`]: ../struct.Builder.html#method.format
-//! [`Write`]: https://doc.rust-lang.org/stable/std/io/trait.Write.html
+//! [`Builder::format`]: crate::Builder::format
+//! [`Write`]: std::io::Write
 
 use std::cell::RefCell;
 use std::fmt::Display;
@@ -80,7 +84,7 @@ impl Default for TimestampPrecision {
 /// A formatter to write logs into.
 ///
 /// `Formatter` implements the standard [`Write`] trait for writing log records.
-/// It also supports terminal colors, through the [`style`] method.
+/// It also supports terminal styling using ANSI escape codes.
 ///
 /// # Examples
 ///
@@ -95,9 +99,8 @@ impl Default for TimestampPrecision {
 /// builder.format(|buf, record| writeln!(buf, "{}: {}", record.level(), record.args()));
 /// ```
 ///
-/// [`Write`]: https://doc.rust-lang.org/stable/std/io/trait.Write.html
-/// [`writeln`]: https://doc.rust-lang.org/stable/std/macro.writeln.html
-/// [`style`]: #method.style
+/// [`Write`]: std::io::Write
+/// [`writeln`]: std::writeln
 pub struct Formatter {
     buf: Rc<RefCell<Buffer>>,
     write_style: WriteStyle,
@@ -129,6 +132,8 @@ impl Formatter {
     /// Get the default [`style::Style`] for the given level.
     ///
     /// The style can be used to print other values besides the level.
+    ///
+    /// See [`style`] for how to adapt it to the styling crate of your choice
     pub fn default_level_style(&self, level: Level) -> style::Style {
         if self.write_style == WriteStyle::Never {
             style::Style::new()
@@ -238,10 +243,6 @@ type SubtleStyle = StyledValue<&'static str>;
 type SubtleStyle = &'static str;
 
 /// A value that can be printed using the given styles.
-///
-/// It is the result of calling [`Style::value`].
-///
-/// [`Style::value`]: struct.Style.html#method.value
 #[cfg(feature = "color")]
 struct StyledValue<T> {
     style: style::Style,
@@ -251,14 +252,13 @@ struct StyledValue<T> {
 #[cfg(feature = "color")]
 impl<T: std::fmt::Display> std::fmt::Display for StyledValue<T> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        let style = self.style.render();
-        let reset = self.style.render_reset();
+        let style = self.style;
 
         // We need to make sure `f`s settings don't get passed onto the styling but do get passed
         // to the value
         write!(f, "{style}")?;
         self.value.fmt(f)?;
-        write!(f, "{reset}")?;
+        write!(f, "{style:#}")?;
         Ok(())
     }
 }

src/fmt/mod.rs

@@ -259,10 +259,6 @@
 //! [gh-repo-examples]: https://github.com/rust-cli/env_logger/tree/main/examples
 //! [level-enum]: https://docs.rs/log/latest/log/enum.Level.html
 //! [log-crate-url]: https://docs.rs/log
-//! [`Builder`]: struct.Builder.html
-//! [`Builder::is_test`]: struct.Builder.html#method.is_test
-//! [`Env`]: struct.Env.html
-//! [`fmt`]: fmt/index.html
 
 #![doc(
     html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",