xilem: New starting page for documentation

xilem/src/lib.rs

@@ -1,8 +1,100 @@
 // Copyright 2024 the Xilem Authors
 // SPDX-License-Identifier: Apache-2.0
 
-//! An experimental Rust native UI framework.
-
+//!
+//! <div align="center" style="margin-bottom: 1em">
+//!
+//! <h1 style="margin: 0; line-height: 1em">Xilem</h1>
+//! <h6 style="margin-top: 0">An experimental Rust native UI framework</h6>
+//!
+//! [Linebender Website] · [Github] · [Community in the Xi Zulip] · [Examples]
+//!
+//! </div>
+//!
+//! Xilem is a UI toolkit. It combines ideas from `Flutter`, `SwiftUI`, and `Elm`. Like all of these, it uses lightweight view objects, diffing them to provide minimal updates to a retained UI. Like `SwiftUI`, it is strongly typed. For more details on Xilem's reactive architecture see Xilem: an [architecture for UI in Rust].
+//!
+//! Xilem's reactive layer is built on top of a wide array of foundational Rust UI projects, e.g.:
+//!
+//! * Widgets are provided by Masonry, which is a fork of the now discontinued `Druid` UI toolkit.
+//! * Rendering is provided by `Vello`, a high performance GPU compute-centric 2D renderer.
+//! * GPU compute infrastructure is provided by wgpu.
+//! * Text support is provided by `Parley`, `Fontique`, `Swash`, and `Skrifa`.
+//! * Accessibility is provided by `AccessKit`.
+//! * Window handling is provided by `winit`.
+//!
+//! Xilem can currently be considered to be in an alpha state. Lots of things need improvements.
+//!
+//! ## Example
+//! The simplest app looks like this:
+//! ```rust
+//! use winit::error::EventLoopError;
+//! use xilem::view::{button, flex, label};
+//! use xilem::{EventLoop, WidgetView, Xilem};
+//!
+//! #[derive(Default, Debug)]
+//! struct AppState {
+//!     num: i32,
+//! }
+//!
+//! fn app_logic(data: &mut AppState) -> impl WidgetView<AppState> {
+//!     flex((label(format!("{data}")), button("increment", |data: &mut AppState| data.num+=1)))
+//! }
+//!
+//! fn main() -> Result<(), EventLoopError> {
+//!     let app = Xilem::new(AppState::default(), app_logic);
+//!     app.run_windowed(EventLoop::with_user_event(), "Counter".into())?;
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Project structure
+//! This diagram gives an idea what the Xilem project is built on:
+//!
+//! ![Demo](https://github.com/linebender/xilem/raw/main/docs/assets/xilem-layers.svg)
+//!
+//! ## View elements
+//! The primitives your Xilem app’s view tree will generally be constructed from:
+//! - [`flex`]: layout defines how items will be arranged in rows or columns.
+//! - [`grid`]: layout divides a window into regions and defines the relationship between inner elements in terms of size and position.
+//! - [`lens`]: an adapter which allows using a component which only uses one field of the current state.
+//! - [`map action`]: provides a message that the parent view has to handle to update the state.
+//! - [`adapt`]: the most flexible but also most verbose way to modularize the views by state and action.
+//! - [`sized box`]: forces its child to have a specific width and/or height.
+//! - [`button`]: button element.
+//! - [`checkbox`]: checkbox element.
+//! - [`image`]: image element.
+//! - [`label`]: label element.
+//! - [`portal`]: portal element.
+//! - [`progress bar`]: progress bar element.
+//! - [`prose`]: prose element.
+//! - [`spinner`]: can be used to display that progress is happening on some process.
+//! - [`task`]: task element.
+//! - [`textbox`]: task element.
+//!
+//! [Linebender Website]: https://linebender.org/
+//! [Github]: https://github.com/linebender/xilem/tree/main/xilem
+//! [Community in the Xi Zulip]: https://xi.zulipchat.com/#narrow/stream/354396-xilem
+//! [Examples]: https://github.com/linebender/xilem/tree/main/xilem/examples
+//! [architecture for UI in Rust]: https://raphlinus.github.io/rust/gui/2022/05/07/ui-architecture.html
+//! [`flex`]: crate::view::flex
+//! [`grid`]: crate::view::grid
+//! [`lens`]: core::lens
+//! [`map state`]: core::map_state
+//! [`map action`]: core::map_action
+//! [`adapt`]: core::adapt
+//! [`sized box`]: crate::view::sized_box
+//! [`button`]: crate::view::button
+//! [`checkbox`]: crate::view::checkbox
+//! [`image`]: crate::view::image
+//! [`label`]: crate::view::label
+//! [`portal`]: crate::view::portal
+//! [`progress bar`]: crate::view::progress_bar
+//! [`prose`]: crate::view::prose
+//! [`spinner`]: crate::view::spinner
+//! [`task`]: crate::view::task
+//! [`textbox`]: crate::view::textbox
+
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46134943?s=48&v=4")]
 // LINEBENDER LINT SET - lib.rs - v1
 // See https://linebender.org/wiki/canonical-lints/
 // These lints aren't included in Cargo.toml because they
@@ -67,6 +159,7 @@ pub mod view;
 pub use any_view::AnyWidgetView;
 pub use driver::{async_action, MasonryDriver, MasonryProxy, ASYNC_MARKER_WIDGET};
 
+/// Runtime builder.
 #[must_use = "A Xilem app does nothing unless ran."]
 pub struct Xilem<State, Logic> {
     state: State,
@@ -108,6 +201,7 @@ where
     }
 
     // TODO: Make windows a specific view
+    /// Run app with default windows attributes
     pub fn run_windowed(
         self,
         // We pass in the event loop builder to allow
@@ -129,6 +223,7 @@ where
     }
 
     // TODO: Make windows into a custom view
+    /// Run app with custom windows attributes
     pub fn run_windowed_in(
         self,
         mut event_loop: EventLoopBuilder,