diff --git a/cursive-core/src/theme/mod.rs b/cursive-core/src/theme/mod.rs
index 587b632..211a41a 100644
--- a/cursive-core/src/theme/mod.rs
+++ b/cursive-core/src/theme/mod.rs
@@ -120,12 +120,36 @@
 //!
 //! # Themes
 //!
-//! A theme defines the color palette an application will use, as well as
-//! various options to style views.
+//! A [`Theme`] object defines the color palette an application will use, as
+//! 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
 //! # Every field in a theme file is optional.
@@ -157,6 +181,19 @@
 //!     highlight          = "#F00"
 //!     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 color;
 mod color_pair;
@@ -244,7 +281,7 @@ impl From<toml::de::Error> for Error {
 }
 
 #[cfg(feature = "toml")]
-/// Loads a theme from file and sets it as active.
+/// Loads a theme from file.
 ///
 /// Must have the `toml` feature enabled.
 pub fn load_theme_file<P: AsRef<Path>>(filename: P) -> Result<Theme, Error> {
diff --git a/cursive/src/lib.rs b/cursive/src/lib.rs
index aff0f47..8da6f10 100644
--- a/cursive/src/lib.rs
+++ b/cursive/src/lib.rs
@@ -54,6 +54,14 @@
 //! and log to it instead of stdout.
 //!
 //! 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)]
 
 pub use cursive_core::*;