[Doc] Improves the documentation about using custom themes

As starting to use the cursive library I've found it challenging to
figure out how to actually use the themes. Only after checking the
source code, and another library actually using this feature, I've
managed to apply it to my project.

This change makes it easier for new commers to use toml themes by
extending the documentationn
This commit is contained in:
maxim 2020-02-13 09:19:51 +03:00 committed by Alexandre Bury
parent 4d322eb42d
commit 63b438188f
2 changed files with 50 additions and 5 deletions

View File

@ -120,12 +120,36 @@
//! //!
//! # Themes //! # Themes
//! //!
//! A theme defines the color palette an application will use, as well as //! A [`Theme`] object defines the color palette an application will use, as
//! various options to style views. //! well as various options to style views.
//! //!
//! Themes are described in toml configuration files. All fields are optional. //! There are several ways to set a theme for the application:
//! //!
//! Here are the possible entries: //! * Construct a [`Theme`] object by setting every field individually.
//! * Get the current theme with [`Cursive::current_theme`] method and
//! changing the required fields (for example see [theme_manual example]).
//! * Using a toml file as a theme configuration (for example see
//! [theme example]).
//!
//! ## Configuring theme with toml
//!
//! This requires the `toml` feature to be enabled.
//!
//! ```toml
//! [dependencies]
//! cursive = { version = "*", features = ["toml"] }
//! ```
//!
//! To use the theme in your application, load it with [`Cursive::load_toml`]
//! method (or use [`theme::load_theme_file`] to aquire the theme object).
//!
//! ```rust,ignore
//! let mut siv = Cursive::dummy();
//! // Embed the theme with the binary.
//! siv.load_toml(include_str!("<path_to_theme_file>.toml")).unwrap();
//! ```
//!
//! Here are the possible entries (all fields are optional):
//! //!
//! ```toml //! ```toml
//! # Every field in a theme file is optional. //! # Every field in a theme file is optional.
@ -157,6 +181,19 @@
//! highlight = "#F00" //! highlight = "#F00"
//! highlight_inactive = "#5555FF" //! highlight_inactive = "#5555FF"
//! ``` //! ```
//!
//! [`Color`]: ./enum.Color.html
//! [`PaletteColor`]: ./enum.PaletteColor.html
//! [`Palette`]: ./struct.Palette.html
//! [`ColorType`]: ./enum.ColorType.html
//! [`ColorStyle`]: ./struct.ColorStyle.html
//! [`Effect`]: ./enum.Effect.html
//! [`Theme`]: ./struct.Theme.html
//! [`Cursive::current_theme`]: ../struct.Cursive.html#method.current_theme
//! [theme_manual example]: https://github.com/gyscos/cursive/blob/master/examples/theme_manual.rs
//! [theme example]: https://github.com/gyscos/cursive/blob/master/examples/theme.rs
//! [`Cursive::load_toml`]: ../struct.Cursive.html#method.load_toml
//! [`theme::load_theme_file`]: ./fn.load_theme_file.html
mod border_style; mod border_style;
mod color; mod color;
mod color_pair; mod color_pair;
@ -244,7 +281,7 @@ impl From<toml::de::Error> for Error {
} }
#[cfg(feature = "toml")] #[cfg(feature = "toml")]
/// Loads a theme from file and sets it as active. /// Loads a theme from file.
/// ///
/// Must have the `toml` feature enabled. /// Must have the `toml` feature enabled.
pub fn load_theme_file<P: AsRef<Path>>(filename: P) -> Result<Theme, Error> { pub fn load_theme_file<P: AsRef<Path>>(filename: P) -> Result<Theme, Error> {

View File

@ -54,6 +54,14 @@
//! and log to it instead of stdout. //! and log to it instead of stdout.
//! //!
//! Or you can use gdb as usual. //! Or you can use gdb as usual.
//!
//! ## Themes
//!
//! Cursive supports configuring the feels and looks of your application with
//! custom themes and colors. For details see documentation of the
//! [`cursive::theme`] module.
//!
//! [`cursive::theme`]: ./theme/index.html
#![deny(missing_docs)] #![deny(missing_docs)]
pub use cursive_core::*; pub use cursive_core::*;