docs(examples): move panic example to examples folder (#1655)

Cargo.lock

@@ -2102,6 +2102,15 @@ dependencies = [
  "syn 2.0.98",
 ]
 
+[[package]]
+name = "panic"
+version = "0.0.0"
+dependencies = [
+ "color-eyre",
+ "crossterm",
+ "ratatui",
+]
+
 [[package]]
 name = "parking_lot"
 version = "0.12.3"

examples/README.md

@@ -118,6 +118,10 @@ Shows how to handle mouse events. [Source](./apps/mouse-drawing/).
 
 Shows how to create a minimal application. [Source](./apps/minimal/).
 
+## Panic demo
+
+Shows how to handle panics in your application. [Source](./apps/panic/).
+
 ## Popup demo
 
 Shows how to handle popups. [Source](./apps/popup/).

examples/apps/panic/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "panic"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/panic/README.md

@@ -0,0 +1,9 @@
+# Panic demo
+
+This example shows how to handle panics in your application.
+
+To run this demo:
+
+```shell
+cargo run -p panic
+```

examples/apps/panic/src/main.rs

@@ -1,43 +1,34 @@
-//! # [Ratatui] Panic Hook example
+/// A Ratatui example that demonstrates how to handle panics in your application.
-//!
+///
-//! The latest version of this example is available in the [examples] folder in the repository.
+/// Prior to Ratatui 0.28.1, a panic hook had to be manually set up to ensure that the terminal
-//!
+/// was reset when a panic occurred. This was necessary because a panic would interrupt the
-//! Please note that the examples are designed to be run against the `main` branch of the Github
+/// normal control flow and leave the terminal in a distorted state.
-//! repository. This means that you may not be able to compile with the latest release version on
+///
-//! crates.io, or the one that you have installed locally.
+/// Starting with Ratatui 0.28.1, the panic hook is automatically set up by the new
-//!
+/// `ratatui::init` function, so you no longer need to manually set up the panic hook. This
-//! See the [examples readme] for more information on finding examples that match the version of the
+/// example now demonstrates how the panic hook acts when it is enabled by default.
-//! library you are using.
+///
-//!
+/// When exiting normally or when handling `Result::Err`, we can reset the terminal manually at
-//! [Ratatui]: https://github.com/ratatui/ratatui
+/// the end of `main` just before we print the error.
-//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+///
-//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+/// Because a panic interrupts the normal control flow, manually resetting the terminal at the
-//!
+/// end of `main` won't do us any good. Instead, we need to make sure to set up a panic hook
-//! Prior to Ratatui 0.28.1, a panic hook had to be manually set up to ensure that the terminal was
+/// that first resets the terminal before handling the panic. This both reuses the standard
-//! reset when a panic occurred. This was necessary because a panic would interrupt the normal
+/// panic hook to ensure a consistent panic handling UX and properly resets the terminal to not
-//! control flow and leave the terminal in a distorted state.
+/// distort the output.
-//!
+///
-//! Starting with Ratatui 0.28.1, the panic hook is automatically set up by the new `ratatui::init`
+/// That's why this example is set up to show both situations, with and without the panic hook,
-//! function, so you no longer need to manually set up the panic hook. This example now demonstrates
+/// to see the difference.
-//! how the panic hook acts when it is enabled by default.
+///
-//!
+/// For more information on how to set this up manually, see the [Color Eyre recipe] in the
-//! When exiting normally or when handling `Result::Err`, we can reset the terminal manually at the
+/// Ratatui website.
-//! end of `main` just before we print the error.
+///
-//!
+/// This example runs with the Ratatui library code in the branch that you are currently
-//! Because a panic interrupts the normal control flow, manually resetting the terminal at the end
+/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
-//! of `main` won't do us any good. Instead, we need to make sure to set up a panic hook that first
+/// release.
-//! resets the terminal before handling the panic. This both reuses the standard panic hook to
+///
-//! ensure a consistent panic handling UX and properly resets the terminal to not distort the
+/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
-//! output.
+/// [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre
-//!
-//! That's why this example is set up to show both situations, with and without the panic hook, to
-//! see the difference.
-//!
-//! For more information on how to set this up manually, see the [Color Eyre recipe] in the Ratatui
-//! website.
-//!
-//! [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre
-
 use color_eyre::{eyre::bail, Result};
 use ratatui::{
     crossterm::event::{self, Event, KeyCode},

ratatui/Cargo.toml

@@ -147,11 +147,6 @@ bench = false
 name = "main"
 harness = false
 
-[[example]]
-name = "panic"
-required-features = ["crossterm"]
-doc-scrape-examples = true
-
 [[example]]
 name = "scrollbar-widget"
 required-features = ["crossterm"]