docs: import prelude::* in doc examples (#490)

This commit adds `prelude::*` all doc examples and widget::* to those
that need it. This is done to highlight the use of the prelude and
simplify the examples.

- Examples in Type and module level comments show all imports and use
  `prelude::*` and `widget::*` where possible.
- Function level comments hide imports unless there are imports other
  than `prelude::*` and `widget::*`.

src/backend/test.rs

@@ -25,7 +25,7 @@ use crate::{
 /// # Example
 ///
 /// ```rust
-/// use ratatui::{prelude::*, backend::TestBackend};
+/// use ratatui::{backend::TestBackend, prelude::*};
 ///
 /// let mut backend = TestBackend::new(10, 2);
 /// backend.clear()?;

src/buffer.rs

@@ -129,9 +129,7 @@ impl Default for Cell {
 /// # Examples:
 ///
 /// ```
-/// use ratatui::buffer::{Buffer, Cell};
-/// use ratatui::layout::Rect;
-/// use ratatui::style::{Color, Style, Modifier};
+/// use ratatui::{prelude::*, buffer::Cell};
 ///
 /// let mut buf = Buffer::empty(Rect{x: 0, y: 0, width: 10, height: 5});
 /// buf.get_mut(0, 2).set_symbol("x");
@@ -228,8 +226,7 @@ impl Buffer {
     /// # Examples
     ///
     /// ```
-    /// # use ratatui::buffer::Buffer;
-    /// # use ratatui::layout::Rect;
+    /// # use ratatui::prelude::*;
     /// let rect = Rect::new(200, 100, 10, 10);
     /// let buffer = Buffer::empty(rect);
     /// // Global coordinates to the top corner of this buffer's area
@@ -241,8 +238,7 @@ impl Buffer {
     /// Panics when given an coordinate that is outside of this Buffer's area.
     ///
     /// ```should_panic
-    /// # use ratatui::buffer::Buffer;
-    /// # use ratatui::layout::Rect;
+    /// # use ratatui::prelude::*;
     /// let rect = Rect::new(200, 100, 10, 10);
     /// let buffer = Buffer::empty(rect);
     /// // Top coordinate is outside of the buffer in global coordinate space, as the Buffer's area
@@ -268,8 +264,7 @@ impl Buffer {
     /// # Examples
     ///
     /// ```
-    /// # use ratatui::buffer::Buffer;
-    /// # use ratatui::layout::Rect;
+    /// # use ratatui::prelude::*;
     /// let rect = Rect::new(200, 100, 10, 10);
     /// let buffer = Buffer::empty(rect);
     /// assert_eq!(buffer.pos_of(0), (200, 100));
@@ -281,8 +276,7 @@ impl Buffer {
     /// Panics when given an index that is outside the Buffer's content.
     ///
     /// ```should_panic
-    /// # use ratatui::buffer::Buffer;
-    /// # use ratatui::layout::Rect;
+    /// # use ratatui::prelude::*;
     /// let rect = Rect::new(0, 0, 10, 10); // 100 cells in total
     /// let buffer = Buffer::empty(rect);
     /// // Index 100 is the 101th cell, which lies outside of the area of this Buffer.

src/layout.rs

@@ -38,7 +38,7 @@ pub enum Constraint {
     /// Converts the given percentage to a f32, and then converts it back, trimming off the decimal
     /// point (effectively rounding down)
     /// ```
-    /// # use ratatui::prelude::Constraint;
+    /// # use ratatui::prelude::*;
     /// assert_eq!(0, Constraint::Percentage(50).apply(0));
     /// assert_eq!(2, Constraint::Percentage(50).apply(4));
     /// assert_eq!(5, Constraint::Percentage(50).apply(10));
@@ -50,7 +50,7 @@ pub enum Constraint {
     /// Converts the given numbers to a f32, and then converts it back, trimming off the decimal
     /// point (effectively rounding down)
     /// ```
-    /// # use ratatui::prelude::Constraint;
+    /// # use ratatui::prelude::*;
     /// assert_eq!(0, Constraint::Ratio(4, 3).apply(0));
     /// assert_eq!(4, Constraint::Ratio(4, 3).apply(4));
     /// assert_eq!(10, Constraint::Ratio(4, 3).apply(10));
@@ -65,7 +65,7 @@ pub enum Constraint {
     /// Apply no more than the given amount (currently roughly equal to [Constraint::Max], but less
     /// consistent)
     /// ```
-    /// # use ratatui::prelude::Constraint;
+    /// # use ratatui::prelude::*;
     /// assert_eq!(0, Constraint::Length(4).apply(0));
     /// assert_eq!(4, Constraint::Length(4).apply(4));
     /// assert_eq!(4, Constraint::Length(4).apply(10));
@@ -75,7 +75,7 @@ pub enum Constraint {
     ///
     /// also see [std::cmp::min]
     /// ```
-    /// # use ratatui::prelude::Constraint;
+    /// # use ratatui::prelude::*;
     /// assert_eq!(0, Constraint::Max(4).apply(0));
     /// assert_eq!(4, Constraint::Max(4).apply(4));
     /// assert_eq!(4, Constraint::Max(4).apply(10));
@@ -85,7 +85,7 @@ pub enum Constraint {
     ///
     /// also see [std::cmp::max]
     /// ```
-    /// # use ratatui::prelude::Constraint;
+    /// # use ratatui::prelude::*;
     /// assert_eq!(4, Constraint::Min(4).apply(0));
     /// assert_eq!(4, Constraint::Min(4).apply(4));
     /// assert_eq!(10, Constraint::Min(4).apply(10));
@@ -302,8 +302,8 @@ pub(crate) enum SegmentSize {
 /// # Example
 ///
 /// ```rust
-/// # use ratatui::prelude::*;
-/// # use ratatui::widgets::Paragraph;
+/// use ratatui::{prelude::*, widgets::*};
+///
 /// fn render<B: Backend>(frame: &mut Frame<B>, area: Rect) {
 ///     let layout = Layout::default()
 ///         .direction(Direction::Vertical)

src/lib.rs

@@ -36,7 +36,7 @@
 //!
 //! ```rust,no_run
 //! use std::io;
-//! use ratatui::{backend::CrosstermBackend, Terminal};
+//! use ratatui::prelude::*;
 //!
 //! fn main() -> Result<(), io::Error> {
 //!     let stdout = io::stdout();
@@ -51,7 +51,7 @@
 //!
 //! ```rust,ignore
 //! use std::io;
-//! use ratatui::{backend::TermionBackend, Terminal};
+//! use ratatui::prelude::*;
 //! use termion::raw::IntoRawMode;
 //!
 //! fn main() -> Result<(), io::Error> {
@@ -79,11 +79,7 @@
 //!
 //! ```rust,no_run
 //! use std::{io, thread, time::Duration};
-//! use ratatui::{
-//!     backend::CrosstermBackend,
-//!     widgets::{Block, Borders},
-//!     Terminal
-//! };
+//! use ratatui::{prelude::*, widgets::*};
 //! use crossterm::{
 //!     event::{self, DisableMouseCapture, EnableMouseCapture},
 //!     execute,
@@ -134,12 +130,8 @@
 //! full customization. And `Layout` is no exception:
 //!
 //! ```rust,no_run
-//! use ratatui::{
-//!     backend::Backend,
-//!     layout::{Constraint, Direction, Layout},
-//!     widgets::{Block, Borders},
-//!     Frame,
-//! };
+//! use ratatui::{prelude::*, widgets::*};
+//!
 //! fn ui<B: Backend>(f: &mut Frame<B>) {
 //!    let chunks = Layout::default()
 //!         .direction(Direction::Vertical)

src/prelude.rs

@@ -9,7 +9,6 @@
 //!
 //! ```rust
 //! use ratatui::{prelude::*, widgets::*};
-//! use ratatui::widgets::{Block, Borders};
 //!
 //! #[derive(Debug, Default, PartialEq, Eq)]
 //! struct Line;

src/style.rs

@@ -11,6 +11,7 @@
 //! readable for most use cases.
 //!
 //! ## Example
+//!
 //! ```
 //! use ratatui::prelude::*;
 //!
@@ -76,7 +77,7 @@ bitflags! {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::style::Modifier;
+    /// use ratatui::{prelude::*};
     ///
     /// let m = Modifier::BOLD | Modifier::ITALIC;
     /// ```
@@ -112,7 +113,8 @@ impl fmt::Debug for Modifier {
 /// Style lets you control the main characteristics of the displayed elements.
 ///
 /// ```rust
-/// # use ratatui::style::{Color, Modifier, Style};
+/// use ratatui::{prelude::*};
+///
 /// Style::default()
 ///     .fg(Color::Black)
 ///     .bg(Color::Green)
@@ -133,9 +135,8 @@ impl fmt::Debug for Modifier {
 /// just S3.
 ///
 /// ```rust
-/// # use ratatui::style::{Color, Modifier, Style};
-/// # use ratatui::buffer::Buffer;
-/// # use ratatui::layout::Rect;
+/// use ratatui::{prelude::*};
+///
 /// let styles = [
 ///     Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC),
 ///     Style::default().bg(Color::Red).add_modifier(Modifier::UNDERLINED),
@@ -164,9 +165,8 @@ impl fmt::Debug for Modifier {
 /// reset all properties until that point use [`Style::reset`].
 ///
 /// ```
-/// # use ratatui::style::{Color, Modifier, Style};
-/// # use ratatui::buffer::Buffer;
-/// # use ratatui::layout::Rect;
+/// use ratatui::{prelude::*};
+///
 /// let styles = [
 ///     Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC),
 ///     Style::reset().fg(Color::Yellow),
@@ -244,7 +244,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::style::{Color, Style};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().fg(Color::Blue);
     /// let diff = Style::default().fg(Color::Red);
     /// assert_eq!(style.patch(diff), Style::default().fg(Color::Red));
@@ -259,7 +259,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::style::{Color, Style};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().bg(Color::Blue);
     /// let diff = Style::default().bg(Color::Red);
     /// assert_eq!(style.patch(diff), Style::default().bg(Color::Red));
@@ -279,7 +279,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::style::{Color, Modifier, Style};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().underline_color(Color::Blue).add_modifier(Modifier::UNDERLINED);
     /// let diff = Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED);
     /// assert_eq!(style.patch(diff), Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED));
@@ -297,7 +297,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::style::{Color, Modifier, Style};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().add_modifier(Modifier::BOLD);
     /// let diff = Style::default().add_modifier(Modifier::ITALIC);
     /// let patched = style.patch(diff);
@@ -317,7 +317,7 @@ impl Style {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::style::{Color, Modifier, Style};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC);
     /// let diff = Style::default().remove_modifier(Modifier::ITALIC);
     /// let patched = style.patch(diff);
@@ -335,7 +335,7 @@ impl Style {
     ///
     /// ## Examples
     /// ```
-    /// # use ratatui::style::{Color, Modifier, Style};
+    /// # use ratatui::prelude::*;
     /// let style_1 = Style::default().fg(Color::Yellow);
     /// let style_2 = Style::default().bg(Color::Red);
     /// let combined = style_1.patch(style_2);

src/style/color.rs

@@ -38,8 +38,9 @@ use std::{
 /// # Example
 ///
 /// ```
-/// use ratatui::style::Color;
 /// use std::str::FromStr;
+/// use ratatui::prelude::*;
+///
 /// assert_eq!(Color::from_str("red"), Ok(Color::Red));
 /// assert_eq!("red".parse(), Ok(Color::Red));
 /// assert_eq!("lightred".parse(), Ok(Color::LightRed));
@@ -145,8 +146,9 @@ impl std::error::Error for ParseColorError {}
 /// # Examples
 ///
 /// ```
-/// # use std::str::FromStr;
-/// # use ratatui::style::Color;
+/// use std::str::FromStr;
+/// use ratatui::prelude::*;
+///
 /// let color: Color = Color::from_str("blue").unwrap();
 /// assert_eq!(color, Color::Blue);
 ///

src/terminal.rs

@@ -85,10 +85,7 @@ where
     /// # Examples
     ///
     /// ```rust
-    /// # use ratatui::Terminal;
-    /// # use ratatui::backend::TestBackend;
-    /// # use ratatui::layout::Rect;
-    /// # use ratatui::widgets::Block;
+    /// # use ratatui::{backend::TestBackend, prelude::*, widgets::*};
     /// # let backend = TestBackend::new(5, 5);
     /// # let mut terminal = Terminal::new(backend).unwrap();
     /// let block = Block::default();
@@ -111,10 +108,7 @@ where
     /// # Examples
     ///
     /// ```rust
-    /// # use ratatui::Terminal;
-    /// # use ratatui::backend::TestBackend;
-    /// # use ratatui::layout::Rect;
-    /// # use ratatui::widgets::{List, ListItem, ListState};
+    /// # use ratatui::{backend::TestBackend, prelude::*, widgets::*};
     /// # let backend = TestBackend::new(5, 5);
     /// # let mut terminal = Terminal::new(backend).unwrap();
     /// let mut state = ListState::default();
@@ -403,11 +397,7 @@ where
     /// ## Insert a single line before the current viewport
     ///
     /// ```rust
-    /// # use ratatui::widgets::{Paragraph, Widget};
-    /// # use ratatui::text::{Line, Span};
-    /// # use ratatui::style::{Color, Style};
-    /// # use ratatui::{Terminal};
-    /// # use ratatui::backend::TestBackend;
+    /// # use ratatui::{backend::TestBackend, prelude::*, widgets::*};
     /// # let backend = TestBackend::new(10, 10);
     /// # let mut terminal = Terminal::new(backend).unwrap();
     /// terminal.insert_before(1, |buf| {

src/text/line.rs

@@ -16,8 +16,7 @@ impl<'a> Line<'a> {
     /// # Examples
     ///
     /// ```rust
-    /// # use ratatui::text::Line;
-    /// # use ratatui::style::{Color, Modifier, Style};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
     /// Line::styled("My text", style);
     /// Line::styled(String::from("My text"), style);
@@ -34,8 +33,7 @@ impl<'a> Line<'a> {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::text::{Span, Line};
-    /// # use ratatui::style::{Color, Style};
+    /// # use ratatui::prelude::*;
     /// let line = Line::from(vec![
     ///     Span::styled("My", Style::default().fg(Color::Yellow)),
     ///     Span::raw(" text"),
@@ -54,9 +52,9 @@ impl<'a> Line<'a> {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::text::{Line, StyledGrapheme};
-    /// # use ratatui::style::{Color, Modifier, Style};
-    /// # use std::iter::Iterator;
+    /// use std::iter::Iterator;
+    /// use ratatui::{prelude::*, text::StyledGrapheme};
+    ///
     /// let line = Line::styled("Text", Style::default().fg(Color::Yellow));
     /// let style = Style::default().fg(Color::Green).bg(Color::Black);
     /// assert_eq!(
@@ -83,8 +81,7 @@ impl<'a> Line<'a> {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::text::{Span, Line};
-    /// # use ratatui::style::{Color, Style, Modifier};
+    /// # use ratatui::prelude::*;
     /// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
     /// let mut raw_line = Line::from(vec![
     ///     Span::raw("My"),
@@ -112,8 +109,7 @@ impl<'a> Line<'a> {
     /// ## Examples
     ///
     /// ```rust
-    /// # use ratatui::text::{Span, Line};
-    /// # use ratatui::style::{Color, Style, Modifier};
+    /// # use ratatui::prelude::*;
     /// let mut line = Line::from(vec![
     ///     Span::styled("My", Style::default().fg(Color::Yellow)),
     ///     Span::styled(" text", Style::default().add_modifier(Modifier::BOLD)),
@@ -135,10 +131,7 @@ impl<'a> Line<'a> {
     /// ## Examples
     ///
     /// ```rust
-    /// # use std::borrow::Cow;
-    /// # use ratatui::layout::Alignment;
-    /// # use ratatui::text::{Span, Line};
-    /// # use ratatui::style::{Color, Style, Modifier};
+    /// # use ratatui::prelude::*;
     /// let mut line = Line::from("Hi, what's up?");
     /// assert_eq!(None, line.alignment);
     /// assert_eq!(Some(Alignment::Right), line.alignment(Alignment::Right).alignment)