docs: improve docs for workspace crates (#1490)

Overall makes improvements in the documentation of the workspace crates and checking them.

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",

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"

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

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

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
+<!-- ⚠️ DO NOT EDIT THIS FILE DIRECTLY, EDIT lib.rs AND THEN RUN `cargo rdme` to update this file. -->
+<!-- cargo-rdme start -->
 
-**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
+to offer better stability for widget library authors. Widget libraries should generally depend
-`ratatui-core`, benefiting from a stable API and reducing the need for frequent updates.
+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.
+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
+We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md)
-for more details on how to get involved.
+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.
+
+<!-- cargo-rdme end -->

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;

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;

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<Color>,
+    /// The background color.
     pub bg: Option<Color>,
+    /// The underline color.
     #[cfg(feature = "underline-color")]
     pub underline_color: Option<Color>,
+    /// 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,

ratatui-core/src/symbols.rs

@@ -1,3 +1,5 @@
+//! Symbols and markers for drawing various widgets.
+
 use strum::{Display, EnumString};
 
 pub mod border;

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
+## enables the [`WidgetRef`](ratatui_core::widgets::WidgetRef) and
-## in the future.
+## [`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)
+## Enables the [`Paragraph::line_count`](paragraph::Paragraph::line_count)
-## [`Paragraph::line_width`](widgets::Paragraph::line_width) methods
+## [`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

ratatui-widgets/README.md

@@ -1,20 +1,24 @@
-# Ratatui-widgets
+# Ratatui Widgets
 
-<!-- DO NOT EDIT THIS FILE DIRECTLY, EDIT lib.rs AND THEN RUN cargo rdme to update this file -->
+[![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)
+
+<!-- ⚠️ DO NOT EDIT THIS FILE DIRECTLY, EDIT lib.rs AND THEN RUN `cargo rdme` to update this file. -->
 <!-- cargo-rdme start -->
 
-Ratatui-widgets contains all the widgets that were previously part of the Ratatui crate. It is
+**ratatui-widgets** contains all the widgets that were previously part of the [Ratatui] crate.
-meant to be used in conjunction with the [Ratatui] crate, which provides the core functionality
+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
+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.
+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.
 
 <!-- cargo-rdme end -->

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
+//! **ratatui-widgets** contains all the widgets that were previously part of the [Ratatui] crate.
-//! meant to be used in conjunction with the [Ratatui] crate, which provides the core functionality
+//! 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
+//! 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.
+//! 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
 //!

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

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<Vec<String>> {
     let meta = MetadataCommand::new()
         .exec()
         .wrap_err("failed to get cargo metadata")?;
-    for package in meta.workspace_default_packages() {
+    Ok(meta
-        run_cargo_nightly(vec!["docs-rs", "--package", &package.name])?;
+        .workspace_default_packages()
-    }
+        .iter()
-    Ok(())
+        .map(|v| v.name.clone())
+        .collect())
 }
 
 /// Lint formatting issues in the project