mirror of
https://github.com/ratatui-org/ratatui
synced 2024-11-10 07:04:17 +00:00
docs(examples): document incompatible examples better (#844)
Examples often take advantage of unreleased API changes, which makes them not copy-paste friendly.
This commit is contained in:
Josh McKinney
GitHub
parent
68d5783a69
commit
41de8846fd
10 changed files with 72 additions and 58 deletions
17
README.md
17
README.md
|
|
@ -74,9 +74,10 @@ for more info.
|
|||
|
||||
The following example demonstrates the minimal amount of code necessary to setup a terminal and
|
||||
render "Hello World!". The full code for this example which contains a little more detail is in
|
||||
[hello_world.rs]. For more guidance on different ways to structure your application see the
|
||||
[Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the various
|
||||
[Examples]. There are also several starter templates in the [templates] repository.
|
||||
the [Examples] directory. For more guidance on different ways to structure your application see
|
||||
the [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
|
||||
various [Examples]. There are also several starter templates available in the [templates]
|
||||
repository.
|
||||
|
||||
Every application built with `ratatui` needs to implement the following steps:
|
||||
|
||||
|
|
@ -289,8 +290,8 @@ Running this example produces the following output:
|
|||
[Handling Events]: https://ratatui.rs/concepts/event-handling/
|
||||
[Layout]: https://ratatui.rs/how-to/layout/
|
||||
[Styling Text]: https://ratatui.rs/how-to/render/style-text/
|
||||
[templates]: https://github.com/ratatui-org/templates
|
||||
[Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
|
||||
[templates]: https://github.com/ratatui-org/templates/
|
||||
[Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
|
||||
[Report a bug]: https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
|
||||
[Request a Feature]: https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
|
||||
[Create a Pull Request]: https://github.com/ratatui-org/ratatui/compare
|
||||
|
|
@ -321,7 +322,6 @@ Running this example produces the following output:
|
|||
[Termion]: https://crates.io/crates/termion
|
||||
[Termwiz]: https://crates.io/crates/termwiz
|
||||
[tui-rs]: https://crates.io/crates/tui
|
||||
[hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
|
||||
[Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
|
||||
[License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
|
||||
[CI Badge]:
|
||||
|
|
@ -387,9 +387,8 @@ The library comes with the following
|
|||
- [Table](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Table.html)
|
||||
- [Tabs](https://docs.rs/ratatui/latest/ratatui/widgets/struct.Tabs.html)
|
||||
|
||||
Each widget has an associated example which can be found in the [examples](./examples/) folder. Run
|
||||
each examples with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by
|
||||
pressing `q`.
|
||||
Each widget has an associated example which can be found in the [Examples] folder. Run each example
|
||||
with cargo (e.g. to run the gauge example `cargo run --example gauge`), and quit by pressing `q`.
|
||||
|
||||
You can also run all examples by running `cargo make run-examples` (requires `cargo-make` that can
|
||||
be installed with `cargo install cargo-make`).
|
||||
|
|
|
|||
|
|
@ -1,22 +1,27 @@
|
|||
# Examples
|
||||
|
||||
> [!WARNING]
|
||||
> The examples in this folder run against the `main` branch. There may be backwards
|
||||
> incompatible changes compared to the [latest stable version](https://github.com/ratatui-org/ratatui/releases/latest).
|
||||
>
|
||||
> If you find that code copied from an example fails to run in your own application, please check
|
||||
> the tag of the release that your project is using.
|
||||
>
|
||||
> To view examples that match the version of Ratatui that you are using checkout the matching tag in
|
||||
> your local git repository, or select the tag in the "Switch branches/tags" button if you're
|
||||
> viewing this file on GitHub.
|
||||
>
|
||||
> To use incompatible example code as is, you can also use the most recent alpha release of Ratatui
|
||||
> (we release these weekly).
|
||||
This folder contains unreleased code. View the [examples for the latest release
|
||||
(0.25.0)](https://github.com/ratatui-org/ratatui/tree/v0.25.0/examples) instead.
|
||||
|
||||
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.
|
||||
> [!WARNING]
|
||||
>
|
||||
> There are backwards incompatible changes in these examples, as they are designed to compile
|
||||
> against the `main` branch.
|
||||
>
|
||||
> There are a few workaround for this problem:
|
||||
>
|
||||
> - View the examples as they were when the latest version was release by selecting the tag that
|
||||
> matches that version. E.g. <https://github.com/ratatui-org/ratatui/tree/v0.25.0/examples>. There
|
||||
> is a combo box at the top of this page which allows you to select any previous tagged version.
|
||||
> - To view the code locally, checkout the tag using `git switch --detach v0.25.0`.
|
||||
> - Use the latest [alpha version of Ratatui]. These are released weekly on Saturdays.
|
||||
> - Compile your code against the main branch either locally by adding e.g. `path = "../ratatui"` to
|
||||
> the dependency, or remotely by adding `git = "https://github.com/ratatui-org/ratatui"`
|
||||
>
|
||||
> For a list of unreleased breaking changes, see [BREAKING-CHANGES.md].
|
||||
>
|
||||
> We don't keep the CHANGELOG updated with unreleased changes, check the git commit history or run
|
||||
> `git-cliff -u` against a cloned version of this repository.
|
||||
|
||||
## Demo2
|
||||
|
||||
|
|
@ -310,11 +315,18 @@ cargo run --example=user_input --features=crossterm
|
|||
|
||||
![User Input][user_input.gif]
|
||||
|
||||
<!--
|
||||
links to images to make it easier to update in bulk
|
||||
These are generated with `vhs publish examples/xxx.gif`
|
||||
## How to update these examples
|
||||
|
||||
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 `images` git branch to avoid bloating the main
|
||||
repository.
|
||||
|
||||
<!--
|
||||
|
||||
Links to images to make them easier to update in bulk. Use the following script to update and upload
|
||||
the examples to the images branch. (Requires push access to the branch).
|
||||
|
||||
To update these examples in bulk:
|
||||
```shell
|
||||
examples/generate.bash
|
||||
```
|
||||
|
|
@ -344,3 +356,6 @@ examples/generate.bash
|
|||
[table.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/table.gif?raw=true
|
||||
[tabs.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/tabs.gif?raw=true
|
||||
[user_input.gif]: https://github.com/ratatui-org/ratatui/blob/images/examples/user_input.gif?raw=true
|
||||
|
||||
[alpha version of Ratatui]: https://crates.io/crates/ratatui/versions
|
||||
[BREAKING-CHANGES.md]: https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@
|
|||
//! # std::io::Result::Ok(())
|
||||
//! ```
|
||||
//!
|
||||
//! See the the [examples] directory for more examples.
|
||||
//! See the the [Examples] directory for more examples.
|
||||
//!
|
||||
//! # Raw Mode
|
||||
//!
|
||||
|
|
@ -96,7 +96,7 @@
|
|||
//! [Crossterm]: https://crates.io/crates/crossterm
|
||||
//! [Termion]: https://crates.io/crates/termion
|
||||
//! [Termwiz]: https://crates.io/crates/termwiz
|
||||
//! [examples]: https://github.com/ratatui-org/ratatui/tree/main/examples#readme
|
||||
//! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
|
||||
//! [Backend Comparison]:
|
||||
//! https://ratatui.rs/concepts/backends/comparison/
|
||||
//! [Ratatui Website]: https://ratatui-org.github.io/ratatui-book
|
||||
|
|
|
|||
|
|
@ -70,14 +70,14 @@ use crate::{
|
|||
/// # std::io::Result::Ok(())
|
||||
/// ```
|
||||
///
|
||||
/// See the the [examples] directory for more examples. See the [`backend`] module documentation
|
||||
/// See the the [Examples] directory for more examples. See the [`backend`] module documentation
|
||||
/// for more details on raw mode and alternate screen.
|
||||
///
|
||||
/// [`Write`]: std::io::Write
|
||||
/// [`Terminal`]: crate::terminal::Terminal
|
||||
/// [`backend`]: crate::backend
|
||||
/// [Crossterm]: https://crates.io/crates/crossterm
|
||||
/// [examples]: https://github.com/ratatui-org/ratatui/tree/main/examples#examples
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
|
||||
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
|
||||
pub struct CrosstermBackend<W: Write> {
|
||||
/// The writer used to send commands to the terminal.
|
||||
|
|
|
|||
|
|
@ -52,14 +52,14 @@ use crate::{
|
|||
/// # std::result::Result::Ok::<(), Box<dyn std::error::Error>>(())
|
||||
/// ```
|
||||
///
|
||||
/// See the the [examples] directory for more examples. See the [`backend`] module documentation
|
||||
/// See the the [Examples] directory for more examples. See the [`backend`] module documentation
|
||||
/// for more details on raw mode and alternate screen.
|
||||
///
|
||||
/// [`backend`]: crate::backend
|
||||
/// [`Terminal`]: crate::terminal::Terminal
|
||||
/// [`BufferedTerminal`]: termwiz::terminal::buffered::BufferedTerminal
|
||||
/// [Termwiz]: https://crates.io/crates/termwiz
|
||||
/// [examples]: https://github.com/ratatui-org/ratatui/tree/main/examples#readme
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
|
||||
pub struct TermwizBackend {
|
||||
buffered_terminal: BufferedTerminal<SystemTerminal>,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -34,9 +34,9 @@ thread_local! {
|
|||
/// many of the constraints as possible.
|
||||
///
|
||||
/// By default, the last chunk of the computed layout is expanded to fill the remaining space. To
|
||||
/// avoid this behavior, add an unused `Constraint::Min(0)` as the last constraint. There is also
|
||||
/// an unstable API to prefer equal chunks if other constraints are all satisfied, see
|
||||
/// [`SegmentSize`] for more info.
|
||||
/// avoid this behavior, add an unused `Constraint::Min(0)` as the last constraint. There is also an
|
||||
/// unstable API to prefer equal chunks if other constraints are all satisfied, see [`SegmentSize`]
|
||||
/// for more info.
|
||||
///
|
||||
/// When the layout is computed, the result is cached in a thread-local cache, so that subsequent
|
||||
/// calls with the same parameters are faster. The cache is a simple HashMap, and grows
|
||||
|
|
@ -78,13 +78,14 @@ thread_local! {
|
|||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// The [`layout.rs` example](https://github.com/ratatui-org/ratatui/blob/main/examples/layout.rs)
|
||||
/// shows the effect of combining constraints:
|
||||
/// See the `layout`, `flex`, and `constraints` examples in the [Examples] folder for more details
|
||||
/// about how to use layouts.
|
||||
///
|
||||
/// 
|
||||
///
|
||||
/// [`cassowary-rs`]: https://crates.io/crates/cassowary
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
|
||||
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
|
||||
pub struct Layout {
|
||||
direction: Direction,
|
||||
|
|
|
|||
|
|
@ -53,8 +53,8 @@
|
|||
//!
|
||||
//! The following example demonstrates the minimal amount of code necessary to setup a terminal and
|
||||
//! render "Hello World!". The full code for this example which contains a little more detail is in
|
||||
//! [hello_world.rs]. For more guidance on different ways to structure your application see the
|
||||
//! [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
|
||||
//! the [Examples] directory. For more guidance on different ways to structure your application see
|
||||
//! the [Application Patterns] and [Hello World tutorial] sections in the [Ratatui Website] and the
|
||||
//! various [Examples]. There are also several starter templates available in the [templates]
|
||||
//! repository.
|
||||
//!
|
||||
|
|
@ -288,7 +288,7 @@
|
|||
//! [Layout]: https://ratatui.rs/how-to/layout/
|
||||
//! [Styling Text]: https://ratatui.rs/how-to/render/style-text/
|
||||
//! [templates]: https://github.com/ratatui-org/templates/
|
||||
//! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples
|
||||
//! [Examples]: https://github.com/ratatui-org/ratatui/tree/main/examples/README.md
|
||||
//! [Report a bug]: https://github.com/ratatui-org/ratatui/issues/new?labels=bug&projects=&template=bug_report.md
|
||||
//! [Request a Feature]: https://github.com/ratatui-org/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
|
||||
//! [Create a Pull Request]: https://github.com/ratatui-org/ratatui/compare
|
||||
|
|
@ -319,7 +319,6 @@
|
|||
//! [Termion]: https://crates.io/crates/termion
|
||||
//! [Termwiz]: https://crates.io/crates/termwiz
|
||||
//! [tui-rs]: https://crates.io/crates/tui
|
||||
//! [hello_world.rs]: https://github.com/ratatui-org/ratatui/blob/main/examples/hello_world.rs
|
||||
//! [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square
|
||||
//! [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square
|
||||
//! [CI Badge]:
|
||||
|
|
|
|||
|
|
@ -21,10 +21,10 @@ use crate::{
|
|||
/// [`offset`]: ListState::offset()
|
||||
/// [`selected`]: ListState::selected()
|
||||
///
|
||||
/// See the [list example] for a more in depth example of the various configuration options and
|
||||
/// for how to handle state.
|
||||
/// See the list in the [Examples] directory for a more in depth example of the various
|
||||
/// configuration options and for how to handle state.
|
||||
///
|
||||
/// [list example]: https://github.com/ratatui-org/ratatui/blob/main/examples/list.rs
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
|
|
@ -364,10 +364,10 @@ where
|
|||
/// the user to [scroll](ListState::offset) through items and [select](ListState::select) one of
|
||||
/// them.
|
||||
///
|
||||
/// See the [list example] for a more in depth example of the various configuration options and for
|
||||
/// how to handle state.
|
||||
/// See the list in the [Examples] directory for a more in depth example of the various
|
||||
/// configuration options and for how to handle state.
|
||||
///
|
||||
/// [list example]: https://github.com/ratatui-org/ratatui/blob/main/examples/list.rs
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/blob/main/examples/README.md
|
||||
///
|
||||
/// # Fluent setters
|
||||
///
|
||||
|
|
|
|||
|
|
@ -26,11 +26,11 @@ use crate::{
|
|||
///
|
||||
/// Note: if the `widths` field is empty, the table will be rendered with equal widths.
|
||||
///
|
||||
/// See the [table example] and the recipe and traceroute tabs in the [demo2 example] for a more in
|
||||
/// depth example of the various configuration options and for how to handle state.
|
||||
/// See the table example and the recipe and traceroute tabs in the demo2 example in the [Examples]
|
||||
/// directory for a more in depth example of the various configuration options and for how to handle
|
||||
/// state.
|
||||
///
|
||||
/// [table example]: https://github.com/ratatui-org/ratatui/blob/master/examples/table.rs
|
||||
/// [demo2 example]: https://github.com/ratatui-org/ratatui/blob/master/examples/demo2/
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/blob/master/examples/README.md
|
||||
///
|
||||
/// # Constructor methods
|
||||
///
|
||||
|
|
|
|||
|
|
@ -12,11 +12,11 @@
|
|||
/// [`offset`]: TableState::offset()
|
||||
/// [`selected`]: TableState::selected()
|
||||
///
|
||||
/// See the [table example] and the recipe and traceroute tabs in the [demo2 example] for a more in
|
||||
/// depth example of the various configuration options and for how to handle state.
|
||||
/// See the `table`` example and the `recipe`` and `traceroute`` tabs in the demo2 example in the
|
||||
/// [Examples] directory for a more in depth example of the various configuration options and for
|
||||
/// how to handle state.
|
||||
///
|
||||
/// [table example]: https://github.com/ratatui-org/ratatui/blob/master/examples/table.rs
|
||||
/// [demo2 example]: https://github.com/ratatui-org/ratatui/blob/master/examples/demo2/
|
||||
/// [Examples]: https://github.com/ratatui-org/ratatui/blob/master/examples/README.md
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
|
|
|
|||
Loading…
Reference in a new issue