From ad2dc5646dae04fa5502e677182cdeb0c3630cce Mon Sep 17 00:00:00 2001 From: Josh McKinney Date: Fri, 20 Oct 2023 12:41:36 -0700 Subject: [PATCH] docs(examples): update examples readme (#576) remove VHS bug info, tweak colors_rgb image, update some of the instructions. add demo2 --- examples/README.md | 43 ++++++++++++++++++++-------------------- examples/colors_rgb.tape | 3 ++- examples/generate.bash | 11 ++++++---- 3 files changed, 30 insertions(+), 27 deletions(-) diff --git a/examples/README.md b/examples/README.md index 05270efe..45e28104 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,10 +1,18 @@ # Examples -These gifs were created using [Charm VHS](https://github.com/charmbracelet/vhs). +These gifs were created using [VHS](https://github.com/charmbracelet/vhs). Each example has a +corresponding `.tape` file that holds instructions for how to generate the images. Note that the +images themselves are stored in a separate git branch to avoid bloating the main repository. -VHS has a problem rendering some background color transitions, which shows up in several examples -below. See for more info. These problems don't -occur in a terminal. +## Demo2 + +This is the demo example from the main README and crate page. Source: [demo2](./demo2/). + +```shell +cargo run --example=demo2 --features=crossterm +``` + +![Demo2][demo2.gif] ## Demo @@ -102,19 +110,20 @@ cargo run --example=colors --features=crossterm Demonstrates the available RGB [`Color`](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html) options. These can be used -in any style field. Source: [colors_rgb.rs](./colors_rgb.rs). +in any style field. Source: [colors_rgb.rs](./colors_rgb.rs). Uses a half block technique to render +two square-ish pixels in the space of a single rectangular terminal cell. ```shell cargo run --example=colors_rgb --features=crossterm ``` -![Colors RGB][colors_rgb.gif] +![Colors RGB][colors_rgb.png] ## Custom Widget Demonstrates how to implement the -[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Source: -[custom_widget.rs](./custom_widget.rs). +[`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) trait. Also shows mouse +interaction. Source: [custom_widget.rs](./custom_widget.rs). ```shell cargo run --example=custom_widget --features=crossterm @@ -127,10 +136,6 @@ cargo run --example=custom_widget --features=crossterm Demonstrates the [`Gauge`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Gauge.html) widget. Source: [gauge.rs](./gauge.rs). -> [!NOTE] The backgrounds render poorly when we generate this example using VHS. This problem -> doesn't generally happen during normal rendering in a terminal. See -> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details. - ```shell cargo run --example=gauge --features=crossterm ``` @@ -139,7 +144,7 @@ cargo run --example=gauge --features=crossterm ## Inline -Demonstrates the +Demonstrates how to use the [`Inline`](https://docs.rs/ratatui/latest/ratatui/terminal/enum.Viewport.html#variant.Inline) Viewport mode for ratatui apps. Source: [inline.rs](./inline.rs). @@ -216,10 +221,6 @@ Demonstrates how to render a widget over the top of previously rendered widgets cargo run --example=popup --features=crossterm ``` -> [!NOTE] The background renders poorly after the popup when we generate this example using VHS. -> This problem doesn't generally happen during normal rendering in a terminal. See -> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details. - ![Popup][popup.gif] ## Scrollbar @@ -238,10 +239,6 @@ cargo run --example=scrollbar --features=crossterm Demonstrates the [`Sparkline`](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Sparkline.html) widget. Source: [sparkline.rs](./sparkline.rs). -> [!NOTE] The background renders poorly in the second sparkline when we generate this example using -> VHS. This problem doesn't generally happen during normal rendering in a terminal. See -> [vhs#344](https://github.com/charmbracelet/vhs/issues/344) for more details. - ```shell cargo run --example=sparkline --features=crossterm ``` @@ -292,15 +289,17 @@ To update these examples in bulk: examples/generate.bash ``` --> + [barchart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/barchart.gif?raw=true [block.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/block.gif?raw=true [calendar.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/calendar.gif?raw=true [canvas.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/canvas.gif?raw=true [chart.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/chart.gif?raw=true [colors.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors.gif?raw=true -[colors_rgb.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors_rgb.gif?raw=true +[colors_rgb.png]: https://github.com/ratatui-org/ratatui/blob/images/examples/colors_rgb.png?raw=true [custom_widget.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/custom_widget.gif?raw=true [demo.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo.gif?raw=true +[demo2.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/demo2.gif?raw=true [gauge.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/gauge.gif?raw=true [hello_world.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/hello_world.gif?raw=true [inline.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/inline.gif?raw=true diff --git a/examples/colors_rgb.tape b/examples/colors_rgb.tape index a8f52863..fafb9310 100644 --- a/examples/colors_rgb.tape +++ b/examples/colors_rgb.tape @@ -3,10 +3,11 @@ Output "target/colors_rgb.gif" Set Theme "Aardvark Blue" Set Width 1200 -Set Height 1410 +Set Height 800 Hide Type "cargo run --example=colors_rgb --features=crossterm" Enter Sleep 2s +Screenshot "target/colors_rgb.png" Show Sleep 1s diff --git a/examples/generate.bash b/examples/generate.bash index a6811255..c82bdbb9 100755 --- a/examples/generate.bash +++ b/examples/generate.bash @@ -5,7 +5,11 @@ # - cargo: https://doc.rust-lang.org/cargo/getting-started/installation.html # - gh: https://github.com/cli/cli # - git: https://git-scm.com/ -# - vhs: https://github.com/charmbracelet/vhs +# - vhs: https://github.com/charmbracelet/vhs - currently this needs to be installed from the +# main branch, as the latest release doesn't support the theme we use or the Screenshot +# command. Install using `go install github.com/charmbracelet/vhs@main`` +# - go: https://golang.org/doc/install +# - ttyd: https://github.com/tsl0922/ttyd # Exit on error. Append "|| true" if you expect an error. set -o errexit @@ -21,9 +25,8 @@ set -o pipefail # ensure that running each example doesn't have to wait for the build cargo build --examples --features=crossterm,all-widgets -for tape in examples/*.tape -do - gif=${tape/examples\/} +for tape in examples/*.tape; do + gif=${tape/examples\//} gif=${gif/.tape/.gif} ~/go/bin/vhs $tape --quiet # this can be pasted into the examples README.md