mirror of
https://github.com/ratatui-org/ratatui
synced 2024-11-24 21:53:21 +00:00
docs: improve docs for workspace crates (#1490)
Overall makes improvements in the documentation of the workspace crates and checking them.
This commit is contained in:
Orhun Parmaksız
GitHub
parent
e7085e3a3e
commit
46902f5587
14 changed files with 115 additions and 42 deletions
2
Cargo.lock
generated
2
Cargo.lock
generated
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,21 +1,25 @@
|
|||
# ratatui-core
|
||||
# Ratatui Core
|
||||
|
||||
[](https://crates.io/crates/ratatui-core)
|
||||
[](https://docs.rs/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
|
||||
`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.
|
||||
|
||||
<!-- cargo-rdme end -->
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
//! Symbols and markers for drawing various widgets.
|
||||
|
||||
use strum::{Display, EnumString};
|
||||
|
||||
pub mod border;
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 -->
|
||||
[](https://crates.io/crates/ratatui-widgets)
|
||||
[](https://docs.rs/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
|
||||
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.
|
||||
|
||||
<!-- cargo-rdme end -->
|
||||
|
|
|
|||
|
|
@ -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
|
||||
//!
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue