Various documentation-related fixes (#2301)

Author: PoignardAzur

CONTRIBUTING.md

@@ -1,7 +1,10 @@
 # How to contribute
 
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+**IMPORTANT:** The Druid project is being discontinued. While we will still accept
+all contributions, we'll prefer bugfixes and documentations improvements to new
+features.
+
+If you still want to contribute, here are the guidelines you need to follow.
 
 ## Changelog
 
@@ -102,7 +105,7 @@ adds Druid as a dependency and it won't even compile.
 For that reason our CI testing always uses the highest version that is still compatible.
 This mimics what a new developer would experience when they start using Druid.
 
-What about the the minimum supported version or all the versions between the minimum and maximum?
+What about the minimum supported version or all the versions between the minimum and maximum?
 It is not practical for us to test all the combinations of possible sub-dependency versions.
 Without testing there can easily be mistakes. Let's say our `Cargo.toml` specifies that
 we depend on the package `foo` version `^1.1.1` and the latest `foo` version is `1.1.3`.

README.md

@@ -13,11 +13,11 @@ performance, a rich palette of interactions (hence a widget library to support
 them), and playing well with the native platform.
 See the [goals section](#Goals) for more details.
 
-Druid's current development is largely driven by its use in [Runebender], a new
-font editor.
+**IMPORTANT:** The Druid project is being discontinued. While we will still accept
+all contributions, we'll prefer bugfixes and documentations improvements to new
+features. Current development effort is focused on [Xilem](https://github.com/linebender/xilem).
 
-We have been doing periodic releases of Druid on crates.io, but it is under
-active development and its API might change. All changes are documented
+We have been doing periodic releases of Druid on crates.io, but the API is still unstable. All changes are documented
 in [the changelog](https://github.com/linebender/druid/blob/master/CHANGELOG.md).
 
 For an overview of some key concepts, see the (work in progress) [Druid book].
@@ -130,7 +130,7 @@ the Rust community is working on a variety of different libraries with
 different goals, so here are some of Druid's non-goals and possible
 alternatives that can offer those capabilities:
 
-- Use the the platform-native widgets or mimic them. ([Relm], [Slint])
+- Use the platform-native widgets or mimic them. ([Relm], [Slint])
 - Embed easily into custom render pipelines. ([Conrod])
 - Adhere to a specific architectural style such as Elm. ([Iced], [Relm])
 - Support rendering to HTML when targeting the web. ([Iced], [Moxie])

docs/book_examples/Cargo.toml

@@ -5,4 +5,5 @@ authors = ["Colin Rofls <[email protected]>"]
 edition = "2018"
 
 [dependencies]
-druid = { path = "../../druid" }
+druid = { path = "../../druid", features = [ "im" ] }
+im = { version = "15.0.0" }

docs/book_examples/src/getting_started_2_md.rs

@@ -0,0 +1,126 @@
+#![allow(unused)]
+
+// ANCHOR: example_1_imports
+use druid::widget::Label;
+use druid::{AppLauncher, Widget, WindowDesc};
+// ANCHOR_END: example_1_imports
+
+// ANCHOR: example_2_imports
+use druid::widget::{Container, Flex, Split};
+use druid::Color;
+// ANCHOR_END: example_2_imports
+
+// ANCHOR: example_3_imports
+use im::Vector;
+// ANCHOR_END: example_3_imports
+
+// ANCHOR: example_3b_imports
+use druid::widget::List;
+// ANCHOR_END: example_3b_imports
+
+// ANCHOR: example_4_imports
+use im::vector;
+// ANCHOR_END: example_4_imports
+
+// ANCHOR: example_5_imports
+use druid::widget::Button;
+// ANCHOR_END: example_5_imports
+
+// ---
+
+// ANCHOR: example_6_imports
+use druid::{Data, Lens};
+// ANCHOR_END: example_6_imports
+
+// ANCHOR: example_6_derive
+#[derive(Clone, Data, Lens)]
+// ANCHOR_END: example_6_derive
+
+// ANCHOR: example_6_struct
+struct TodoList {
+    items: Vector<String>,
+    next_item: String,
+}
+// ANCHOR_END: example_6_struct
+
+// ANCHOR: example_7_imports
+use druid::widget::LensWrap;
+// ANCHOR_END: example_7_imports
+
+fn build_example_7() -> impl Widget<TodoList> {
+    // ANCHOR: example_7
+    // Replace previous List with:
+    LensWrap::new(
+        List::new(|| Label::dynamic(|data, _| format!("List item: {}", data))),
+        TodoList::items,
+    )
+    // ANCHOR_END: example_7
+}
+
+fn build_example_7b() -> impl Widget<TodoList> {
+    // ANCHOR: example_7b
+    // Replace previous Button with:
+    Button::new("Add item").on_click(|_, data: &mut TodoList, _| {
+        data.items.push_back(data.next_item.clone());
+        data.next_item = String::new();
+    })
+    // ANCHOR_END: example_7b
+}
+
+// ANCHOR: example_8_imports
+use druid::widget::TextBox;
+// ANCHOR_END: example_8_imports
+
+fn build_example_8() -> impl Widget<TodoList> {
+    // ANCHOR: example_8
+    // Replace `Label::new("Textbox placeholder")` with
+    LensWrap::new(TextBox::new(), TodoList::next_item)
+    // ANCHOR_END: example_8
+}
+
+// ANCHOR: complete_code
+fn build_ui() -> impl Widget<TodoList> {
+    Split::columns(
+        Container::new(
+            // Dynamic list of Widgets
+            LensWrap::new(
+                List::new(|| Label::dynamic(|data, _| format!("List item: {}", data))),
+                TodoList::items,
+            ),
+        )
+        .border(Color::grey(0.6), 2.0),
+        Container::new(
+            Flex::column()
+                .with_flex_child(
+                    Button::new("Add item").on_click(|_, data: &mut TodoList, _| {
+                        data.items.push_back(data.next_item.clone());
+                        data.next_item = String::new();
+                    }),
+                    1.0,
+                )
+                .with_flex_child(LensWrap::new(TextBox::new(), TodoList::next_item), 1.0),
+        )
+        .border(Color::grey(0.6), 2.0),
+    )
+}
+
+fn main() {
+    let main_window = WindowDesc::new(build_ui())
+        .window_size((600.0, 400.0))
+        .title("My first Druid App");
+    let initial_data = TodoList {
+        items: vector![
+            "first item".into(),
+            "second item".into(),
+            "third item".into(),
+            "foo".into(),
+            "bar".into(),
+        ],
+        next_item: String::new(),
+    };
+
+    AppLauncher::with_window(main_window)
+        .launch(initial_data)
+        .expect("Failed to launch application");
+}
+// ANCHOR_END: complete_code

docs/book_examples/src/getting_started_md.rs

@@ -0,0 +1,122 @@
+#![allow(clippy::let_unit_value)]
+
+// ANCHOR: example_1_imports
+use druid::widget::Label;
+use druid::{AppLauncher, Widget, WindowDesc};
+// ANCHOR_END: example_1_imports
+
+// ANCHOR: example_2_imports
+use druid::widget::{Container, Flex, Split};
+use druid::Color;
+// ANCHOR_END: example_2_imports
+
+// ANCHOR: example_3_imports
+use im::Vector;
+// ANCHOR_END: example_3_imports
+
+// ANCHOR: example_3b_imports
+use druid::widget::List;
+// ANCHOR_END: example_3b_imports
+
+// ANCHOR: example_4_imports
+use im::vector;
+// ANCHOR_END: example_4_imports
+
+// ANCHOR: example_5_imports
+use druid::widget::Button;
+// ANCHOR_END: example_5_imports
+
+// ANCHOR: example_1
+fn build_ui() -> impl Widget<()> {
+    Label::new("Hello world")
+}
+
+fn main() {
+    let main_window = WindowDesc::new(build_ui())
+        .window_size((600.0, 400.0))
+        .title("My first Druid App");
+    let initial_data = ();
+
+    AppLauncher::with_window(main_window)
+        .launch(initial_data)
+        .expect("Failed to launch application");
+}
+// ANCHOR_END: example_1
+
+fn build_example_2() -> impl Widget<()> {
+    // ANCHOR: example_2_builder
+    Split::columns(
+        Container::new(
+            Flex::column()
+                .with_flex_child(Label::new("first item"), 1.0)
+                .with_flex_child(Label::new("second item"), 1.0)
+                .with_flex_child(Label::new("third item"), 1.0)
+                .with_flex_child(Label::new("fourth item"), 1.0),
+        )
+        .border(Color::grey(0.6), 2.0),
+        Container::new(
+            Flex::column()
+                .with_flex_child(Label::new("Button placeholder"), 1.0)
+                .with_flex_child(Label::new("Textbox placeholder"), 1.0),
+        )
+        .border(Color::grey(0.6), 2.0),
+    )
+    // ANCHOR_END: example_2_builder
+}
+
+type TodoList = Vector<String>;
+
+fn build_example_3() -> impl Widget<TodoList> {
+    // ANCHOR: example_3_builder
+    Split::columns(
+        Container::new(
+            // Dynamic list of Widgets
+            List::new(|| Label::dynamic(|data, _| format!("List item: {}", data))),
+        )
+        .border(Color::grey(0.6), 2.0),
+        Container::new(
+            Flex::column()
+                .with_flex_child(Label::new("Button placeholder"), 1.0)
+                .with_flex_child(Label::new("Textbox placeholder"), 1.0),
+        )
+        .border(Color::grey(0.6), 2.0),
+    )
+    // ANCHOR_END: example_3_builder
+}
+
+fn example_4_main() {
+    fn build_ui() -> impl Widget<TodoList> {
+        build_example_3()
+    }
+
+    // ANCHOR: example_4_main
+    let main_window = WindowDesc::new(build_ui())
+        .window_size((600.0, 400.0))
+        .title("My first Druid App");
+    let initial_data = vector![
+        "first item".into(),
+        "second item".into(),
+        "third item".into(),
+        "foo".into(),
+        "bar".into(),
+    ];
+
+    AppLauncher::with_window(main_window)
+        .launch(initial_data)
+        .expect("Failed to launch application");
+    // ANCHOR_END: example_4_main
+}
+
+fn build_example_5a() -> impl Widget<TodoList> {
+    // ANCHOR: example_5a_button
+    // Replace `Label::new("Button placeholder")` with
+    Button::new("Add item")
+    // ANCHOR_END: example_5a_button
+}
+
+fn build_example_5b() -> impl Widget<TodoList> {
+    // ANCHOR: example_5b_button
+    Button::new("Add item")
+        .on_click(|_, data: &mut Vector<String>, _| data.push_back("New item".into()))
+    // ANCHOR_END: example_5b_button
+}

docs/book_examples/src/lib.rs

@@ -5,5 +5,7 @@
 mod custom_widgets_md;
 mod data_md;
 mod env_md;
+mod getting_started_2_md;
+mod getting_started_md;
 mod lens_md;
 mod widget_md;

docs/src/intro.md docs/src/01_overview.md

@@ -1,5 +1,7 @@
 # Druid
 
+**Note:** Druid is being discontinued in favor of other projects based on the same general principles, such as [Xilem](https://github.com/linebender/xilem/).
+
 Druid is a framework for building simple graphical applications.
 
 Druid is composed of a number of related projects. [`druid-shell`] is a
@@ -8,17 +10,17 @@ current OS & window manager. [`piet`] is an abstraction for doing 2D graphics;
 [`kurbo`] is a library for 2D geometry; and [`druid`] itself is an opinionated set of
 high-level APIs for building cross-platform desktop applications.
 
-Druid is *data oriented*. It shares many ideas (and is directly inspired by)
+The framework is *data oriented*. It shares many ideas (and is directly inspired by)
 contemporary declarative UI frameworks such as [Flutter], [Jetpack Compose],
 and [SwiftUI], while also attempting to be conceptually simple and largely
 *non-magical*. A programmer familiar with Rust should be able to understand how
 Druid works without special difficulty.
 
-## Goals and Status
+## Prerequisites
 
-The current goal of Druid is to make it easy to write a program in Rust that
-can present a GUI and accept user input. Running your program should be as
-simple as `cargo run`.
+This tutorial assumes basic familliarity with Rust and a working setup with the basic tooling like
+Rustup and Cargo. This tutorial will use stable Rust (v1.65.0 at the time of writing) and the latest
+released version of Druid (v0.8).
 
 ## Key Concepts