diff --git a/Cargo.lock b/Cargo.lock index f1fdba7f..9cecc1dd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2127,6 +2127,7 @@ dependencies = [ "bitflags 2.6.0", "cassowary", "compact_str", + "document-features", "indoc", "instability", "itertools 0.13.0", @@ -2148,6 +2149,7 @@ name = "ratatui-widgets" version = "0.3.0" dependencies = [ "bitflags 2.6.0", + "document-features", "indoc", "instability", "itertools 0.13.0", diff --git a/Cargo.toml b/Cargo.toml index 22f85c4f..2db23a6b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -25,6 +25,7 @@ rust-version = "1.74.0" [workspace.dependencies] bitflags = "2.6.0" +document-features = "0.2.7" indoc = "2.0.5" instability = "0.3.1" itertools = "0.13.0" diff --git a/README.md b/README.md index 531ca105..4c42c0e3 100644 --- a/README.md +++ b/README.md @@ -293,7 +293,7 @@ fn draw(frame: &mut Frame) { [Layout]: https://ratatui.rs/how-to/layout/ [Styling Text]: https://ratatui.rs/how-to/render/style-text/ [templates]: https://github.com/ratatui/templates/ -[Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md +[Examples]: https://github.com/ratatui/ratatui/tree/main/examples/README.md [Report a bug]: https://github.com/ratatui/ratatui/issues/new?labels=bug&projects=&template=bug_report.md [Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md [Create a Pull Request]: https://github.com/ratatui/ratatui/compare diff --git a/ratatui-core/Cargo.toml b/ratatui-core/Cargo.toml index 0c30c396..1f21ce75 100644 --- a/ratatui-core/Cargo.toml +++ b/ratatui-core/Cargo.toml @@ -47,6 +47,7 @@ rustdoc-args = ["--cfg", "docsrs"] bitflags = "2.3" cassowary = "0.3" compact_str = "0.8.0" +document-features = { workspace = true, optional = true } instability.workspace = true indoc.workspace = true itertools.workspace = true diff --git a/ratatui-core/README.md b/ratatui-core/README.md index b98a46f7..553544ed 100644 --- a/ratatui-core/README.md +++ b/ratatui-core/README.md @@ -1,21 +1,25 @@ -# ratatui-core +# Ratatui Core [![Crates.io](https://img.shields.io/crates/v/ratatui-core)](https://crates.io/crates/ratatui-core) [![Documentation](https://docs.rs/ratatui-core/badge.svg)](https://docs.rs/ratatui-core) [![License](https://img.shields.io/crates/l/ratatui-core)](../LICENSE) -## Overview + + -**ratatui-core** is the core library of the [ratatui](https://github.com/ratatui/ratatui) project, +**ratatui-core** is the core library of the [ratatui] project, providing the essential building blocks for creating rich terminal user interfaces in Rust. -### Why ratatui-core? +[ratatui]: https://github.com/ratatui/ratatui + +### Why `ratatui-core`? The `ratatui-core` crate is split from the main [`ratatui`](https://crates.io/crates/ratatui) crate -to offer better stability for widget library authors. Widget libraries should generally depend on -`ratatui-core`, benefiting from a stable API and reducing the need for frequent updates. -Applications, on the other hand, should depend on the main `ratatui` crate, which includes built-in -widgets and additional features. +to offer better stability for widget library authors. Widget libraries should generally depend +on `ratatui-core`, benefiting from a stable API and reducing the need for frequent updates. + +Applications, on the other hand, should depend on the main `ratatui` crate, which includes +built-in widgets and additional features. ## Installation @@ -27,9 +31,11 @@ cargo add ratatui-core ## Contributing -We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md) guide -for more details on how to get involved. +We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md) +guide for more details on how to get involved. -## License +### License This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details. + + diff --git a/ratatui-core/src/layout.rs b/ratatui-core/src/layout.rs index 5ee76355..f7e2cf18 100644 --- a/ratatui-core/src/layout.rs +++ b/ratatui-core/src/layout.rs @@ -1,4 +1,5 @@ #![warn(clippy::missing_const_for_fn)] +//! Provides types and traits for working with layout and positioning in the terminal. mod alignment; mod constraint; diff --git a/ratatui-core/src/lib.rs b/ratatui-core/src/lib.rs index 0c936973..fa1ae2cd 100644 --- a/ratatui-core/src/lib.rs +++ b/ratatui-core/src/lib.rs @@ -1,4 +1,36 @@ -#![doc = include_str!("../README.md")] +//! **ratatui-core** is the core library of the [ratatui] project, +//! providing the essential building blocks for creating rich terminal user interfaces in Rust. +//! +//! [ratatui]: https://github.com/ratatui/ratatui +//! +//! ## Why `ratatui-core`? +//! +//! The `ratatui-core` crate is split from the main [`ratatui`](https://crates.io/crates/ratatui) crate +//! to offer better stability for widget library authors. Widget libraries should generally depend +//! on `ratatui-core`, benefiting from a stable API and reducing the need for frequent updates. +//! +//! Applications, on the other hand, should depend on the main `ratatui` crate, which includes +//! built-in widgets and additional features. +//! +//! # Installation +//! +//! Add `ratatui-core` to your `Cargo.toml`: +//! +//! ```shell +//! cargo add ratatui-core +//! ``` +#![cfg_attr(feature = "document-features", doc = "\n## Features")] +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] +//! +//! # Contributing +//! +//! We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md) +//! guide for more details on how to get involved. +//! +//! ## License +//! +//! This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details. + pub mod buffer; pub mod layout; pub mod style; diff --git a/ratatui-core/src/style.rs b/ratatui-core/src/style.rs index a9a85239..0a6a2eab 100644 --- a/ratatui-core/src/style.rs +++ b/ratatui-core/src/style.rs @@ -244,11 +244,16 @@ impl fmt::Debug for Modifier { #[derive(Default, Clone, Copy, Eq, PartialEq, Hash)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct Style { + /// The foreground color. pub fg: Option, + /// The background color. pub bg: Option, + /// The underline color. #[cfg(feature = "underline-color")] pub underline_color: Option, + /// The modifiers to add. pub add_modifier: Modifier, + /// The modifiers to remove. pub sub_modifier: Modifier, } @@ -275,6 +280,7 @@ impl Styled for Style { } impl Style { + /// Returns a `Style` with default properties. pub const fn new() -> Self { Self { fg: None, diff --git a/ratatui-core/src/symbols.rs b/ratatui-core/src/symbols.rs index 8d39e825..9fc72c4a 100644 --- a/ratatui-core/src/symbols.rs +++ b/ratatui-core/src/symbols.rs @@ -1,3 +1,5 @@ +//! Symbols and markers for drawing various widgets. + use strum::{Display, EnumString}; pub mod border; diff --git a/ratatui-widgets/Cargo.toml b/ratatui-widgets/Cargo.toml index 97e003b8..94fdef69 100644 --- a/ratatui-widgets/Cargo.toml +++ b/ratatui-widgets/Cargo.toml @@ -2,6 +2,7 @@ name = "ratatui-widgets" description = "A collection of Ratatui widgets for building terminal user interfaces." version = "0.3.0" +readme = "README.md" authors.workspace = true documentation.workspace = true repository.workspace = true @@ -14,6 +15,9 @@ edition.workspace = true rust-version.workspace = true [features] +## enables `unstable-widget-ref` as default +default = ["unstable-widget-ref"] + ## enables serialization and deserialization of style and color types using the [`serde`] crate. ## This is useful if you want to save themes to a file. serde = ["dep:serde", "ratatui-core/serde"] @@ -24,18 +28,18 @@ serde = ["dep:serde", "ratatui-core/serde"] ## enables all widgets. all-widgets = ["calendar"] -## enables the [`calendar`](widgets::calendar) widget module and adds a dependency on [`time`]. +## enables the [`calendar`](calendar) widget module and adds a dependency on [`time`]. calendar = ["dep:time"] ## Enable all unstable features. unstable = ["unstable-rendered-line-info", "unstable-widget-ref"] -## enables the [`WidgetRef`] and [`StatefulWidgetRef`] traits which are experimental and may change -## in the future. +## enables the [`WidgetRef`](ratatui_core::widgets::WidgetRef) and +## [`StatefulWidgetRef`](ratatui_core::widgets::StatefulWidgetRef) traits which are experimental and may change unstable-widget-ref = ["ratatui-core/unstable-widget-ref"] -## Enables the [`Paragraph::line_count`](widgets::Paragraph::line_count) -## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods +## Enables the [`Paragraph::line_count`](paragraph::Paragraph::line_count) +## [`Paragraph::line_width`](paragraph::Paragraph::line_width) methods ## which are experimental and may change in the future. ## See [Issue 293](https://github.com/ratatui/ratatui/issues/293) for more details. unstable-rendered-line-info = [] @@ -55,6 +59,7 @@ time = { version = "0.3.11", optional = true, features = ["local-offset"] } unicode-segmentation.workspace = true unicode-width.workspace = true serde = { workspace = true, optional = true } +document-features = { workspace = true, optional = true } [dev-dependencies] rstest.workspace = true diff --git a/ratatui-widgets/README.md b/ratatui-widgets/README.md index bd99a5ce..0805e068 100644 --- a/ratatui-widgets/README.md +++ b/ratatui-widgets/README.md @@ -1,20 +1,24 @@ -# Ratatui-widgets +# Ratatui Widgets - +[![Crates.io](https://img.shields.io/crates/v/ratatui-widgets)](https://crates.io/crates/ratatui-widgets) +[![Documentation](https://docs.rs/ratatui-widgets/badge.svg)](https://docs.rs/ratatui-widgets) +[![License](https://img.shields.io/crates/l/ratatui-widgets)](../LICENSE) + + -Ratatui-widgets contains all the widgets that were previously part of the Ratatui crate. It is -meant to be used in conjunction with the [Ratatui] crate, which provides the core functionality +**ratatui-widgets** contains all the widgets that were previously part of the [Ratatui] crate. +It is meant to be used in conjunction with `ratatui`, which provides the core functionality for building terminal user interfaces. [Ratatui]: https://crates.io/crates/ratatui -Most applications shouldn't need to depend directly on Ratatui-widgets, as all the Ratatui crate +Most applications shouldn't need to depend directly on `ratatui-widgets`, `ratatui` crate re-exports all the widgets from this crate. However, if you are building a widget library that -internally uses Ratatui widgets, or if you prefer finer grained dependencies, you may want to -depend on this crate rather than transitively through the Ratatui crate. +internally uses these widgets, or if you prefer finer grained dependencies, you may want to +depend on this crate rather than transitively through the `ratatui` crate. -Previously, a crate named `Ratatui-widgets` was published with some formative ideas about an +Previously, a crate named `ratatui-widgets` was published with some formative ideas about an eventual Ratatui framework. That crate is now move to [tui-framework-experiment], pending a new name. @@ -62,7 +66,7 @@ cargo add ratatui-widgets [`Table`]: https://docs.rs/ratatui-widgets/latest/ratatui_widgets/table/struct.Table.html [`Tabs`]: https://docs.rs/ratatui-widgets/latest/ratatui_widgets/tabs/struct.Tabs.html -All these widgets are re-exported directly under `ratatui::widgets` in the Ratatui crate. +All these widgets are re-exported directly under `ratatui::widgets` in the `ratatui` crate. ## Contributing @@ -71,6 +75,6 @@ details on contributing, please see the [CONTRIBUTING](CONTRIBUTING.md) document ## License -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details. diff --git a/ratatui-widgets/src/lib.rs b/ratatui-widgets/src/lib.rs index 5041be8f..90933d93 100644 --- a/ratatui-widgets/src/lib.rs +++ b/ratatui-widgets/src/lib.rs @@ -1,16 +1,16 @@ #![warn(missing_docs)] -//! Ratatui-widgets contains all the widgets that were previously part of the Ratatui crate. It is -//! meant to be used in conjunction with the [Ratatui] crate, which provides the core functionality +//! **ratatui-widgets** contains all the widgets that were previously part of the [Ratatui] crate. +//! It is meant to be used in conjunction with `ratatui`, which provides the core functionality //! for building terminal user interfaces. //! //! [Ratatui]: https://crates.io/crates/ratatui //! -//! Most applications shouldn't need to depend directly on Ratatui-widgets, as all the Ratatui crate +//! Most applications shouldn't need to depend directly on `ratatui-widgets`, `ratatui` crate //! re-exports all the widgets from this crate. However, if you are building a widget library that -//! internally uses Ratatui widgets, or if you prefer finer grained dependencies, you may want to -//! depend on this crate rather than transitively through the Ratatui crate. +//! internally uses these widgets, or if you prefer finer grained dependencies, you may want to +//! depend on this crate rather than transitively through the `ratatui` crate. //! -//! Previously, a crate named `Ratatui-widgets` was published with some formative ideas about an +//! Previously, a crate named `ratatui-widgets` was published with some formative ideas about an //! eventual Ratatui framework. That crate is now move to [tui-framework-experiment], pending a new //! name. //! @@ -58,7 +58,9 @@ //! [`Table`]: crate::table::Table //! [`Tabs`]: crate::tabs::Tabs //! -//! All these widgets are re-exported directly under `ratatui::widgets` in the Ratatui crate. +//! All these widgets are re-exported directly under `ratatui::widgets` in the `ratatui` crate. +#![cfg_attr(feature = "document-features", doc = "\n## Features")] +#![cfg_attr(feature = "document-features", doc = document_features::document_features!())] //! //! # Contributing //! diff --git a/ratatui/Cargo.toml b/ratatui/Cargo.toml index 4b9e1e74..be6b05a9 100644 --- a/ratatui/Cargo.toml +++ b/ratatui/Cargo.toml @@ -16,7 +16,7 @@ rust-version.workspace = true [dependencies] crossterm = { version = "0.28.1", optional = true } -document-features = { version = "0.2.7", optional = true } +document-features = { workspace = true, optional = true } indoc = "2" instability.workspace = true itertools.workspace = true @@ -102,7 +102,7 @@ unnecessary_self_imports = "warn" use_self = "warn" [features] -#! The crate provides a set of optional features that can be enabled in your `cargo.toml` file. +#! The crate provides a set of optional features that can be enabled in your `Cargo.toml` file. #! ## By default, we enable the crossterm backend as this is a reasonable choice for most applications ## as it is supported on Linux/Mac/Windows systems. We also enable the `underline-color` feature diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 67303b53..a5e5f688 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -172,7 +172,10 @@ fn check() -> Result<()> { /// Run cargo-rdme to check if README.md is up-to-date with the library documentation fn check_readme() -> Result<()> { - run_cargo(vec!["rdme", "--workspace-project", "ratatui", "--check"]) + for package in get_workspace_packages()? { + run_cargo(vec!["rdme", "--workspace-project", &package, "--check"])?; + } + Ok(()) } /// Generate code coverage report @@ -229,13 +232,21 @@ fn fix_clippy() -> Result<()> { /// Check that docs build without errors using flags for docs.rs fn lint_docs() -> Result<()> { + for package in get_workspace_packages()? { + run_cargo_nightly(vec!["docs-rs", "--package", &package])?; + } + Ok(()) +} + +fn get_workspace_packages() -> Result> { let meta = MetadataCommand::new() .exec() .wrap_err("failed to get cargo metadata")?; - for package in meta.workspace_default_packages() { - run_cargo_nightly(vec!["docs-rs", "--package", &package.name])?; - } - Ok(()) + Ok(meta + .workspace_default_packages() + .iter() + .map(|v| v.name.clone()) + .collect()) } /// Lint formatting issues in the project