subscriber: document ansi behavior of pretty()

Author: katelyn martin

tracing-subscriber/src/fmt/format/mod.rs

@@ -294,6 +294,21 @@ impl<F, T> Format<F, T> {
     /// See [`Pretty`].
     ///
     /// Note that this requires the "ansi" feature to be enabled.
+    ///
+    /// # Options
+    ///
+    /// [`Format::with_ansi`] can be used to disable ANSI formatting in event formatting. However,
+    /// a field formatter must be manually provided to avoid ANSI in the formatting of parent
+    /// spans, like so:
+    ///
+    /// ```
+    /// tracing_subscriber::fmt()
+    ///    .pretty()
+    ///    .with_ansi(false)
+    ///    .fmt_fields(format::PrettyFields::new().with_ansi(false))
+    ///    // ... other settings ...
+    ///    .init();
+    /// ```
     #[cfg(feature = "ansi")]
     #[cfg_attr(docsrs, doc(cfg(feature = "ansi")))]
     pub fn pretty(self) -> Format<Pretty, T> {