Merge pull request #46 from museun/example_runner

make the doc tests actually compile

Author: museun

readme.md renamed to README.md

@@ -5,6 +5,16 @@
 
 too -- a different kind of tui library
 
+## Feature flags
+
+| Flag       | Description                                                                         | Default |
+| ---------- | ----------------------------------------------------------------------------------- | ------- |
+| `terminal` | enable the terminal backend                                                         | `true`  |
+| `sync`     | enable `Send`+`Sync` wrappers                                                       | `false` |
+| `profile`  | enable [`profiling`](https://docs.rs/profiling/1.0.16/profiling/index.html) support | `false` |
+
+---
+
 ## Simple examples
 
 ### Centering some text:
@@ -50,12 +60,12 @@ struct App {
 
 impl App {
     fn view(&mut self, ui: &Ui) {
-        ui.slider(&mut value);
+        ui.slider(&mut self.value);
     }
 }
 
 fn main() -> std::io::Result<()> {
-    let mut app = App::default()
+    let mut app = App::default();
     too::run(|ui| app.view(ui))
 }
 ```
@@ -70,7 +80,7 @@ struct State {
     value: f32
 }
 
-struct App ;
+struct App;
 
 impl App {
     fn view(&self, state: &mut State, ui: &Ui) {
@@ -87,6 +97,8 @@ fn main() -> std::io::Result<()> {
 
 Some pre-made views are provided in: [`too::views`](crate::views)
 
+---
+
 License: MIT OR Apache-2.0
 
 [docs_badge]: https://docs.rs/too/badge.svg

src/lib.rs

@@ -9,15 +9,15 @@
 //!
 //! # Simple examples
 //! ## Centering some text:
-//! ```rust,no_run
+//! ```no_run
 //! fn main() -> std::io::Result<()> {
 //!     too::run(|ui| {
 //!         ui.center(|ui| ui.label("hello world"));
 //!     })
 //! }
 //! ```
 //! ## A pair of buttons to increment and decrement a counter
-//! ```rust,no_run
+//! ```no_run
 //! fn main() -> std::io::Result<()> {
 //!     let mut counter = 0;
 //!     too::run(|ui| {
@@ -36,7 +36,7 @@
 //! }
 //! ```
 //! ## Storing state in a struct
-//! ```rust,no_run
+//! ```no_run
 //! use too::view::Ui;
 //!
 //! #[derive(Default)]
@@ -51,20 +51,20 @@
 //! }
 //!
 //! fn main() -> std::io::Result<()> {
-//!     let mut app = App::default()
+//!     let mut app = App::default();
 //!     too::run(|ui| app.view(ui))
 //! }
 //! ```
 //! ## Storing state seperately from an application
-//! ```rust,no_run
+//! ```no_run
 //! use too::view::Ui;
 //!
 //! #[derive(Default)]
 //! struct State {
 //!     value: f32
 //! }
 //!
-//! struct App ;
+//! struct App;
 //!
 //! impl App {
 //!     fn view(&self, state: &mut State, ui: &Ui) {
@@ -103,9 +103,19 @@ mod str;
 pub use str::Str;
 
 #[doc(hidden)]
-pub use compact_str::format_compact as __dont_use_this_because_semver;
+pub use compact_str::format_compact as ඞ_dont_use_this_because_semver;
 
 #[cfg(feature = "terminal")]
 mod run;
 #[cfg(feature = "terminal")]
 pub use run::{application, run, RunConfig};
+
+#[doc(hidden)]
+pub fn ඞrun_in_docs<R: 'static>(app: impl FnMut(&crate::view::Ui) -> R) -> std::io::Result<()> {
+    view::State::default().build(math::rect(math::vec2(80, 25)), app);
+    Ok(())
+}
+
+#[doc = include_str!("../README.md")]
+#[cfg(doctest)]
+pub struct ReadmeDocTests;

src/str.rs

@@ -60,6 +60,6 @@ where
 #[macro_export]
 macro_rules! format_str {
     ($($arg:tt)*) => {
-        $crate::Str::from($crate::__dont_use_this_because_semver!($($arg)*))
+        $crate::Str::from($crate::ඞ_dont_use_this_because_semver!($($arg)*))
     }
 }

src/view/builder.rs

@@ -20,7 +20,9 @@ use super::{EventCtx, Handled, Interest, IntrinsicSize, Layout, Render, Response
 /// 'v lifetime. Views cannot borrow data as they must be 'static
 ///
 /// ### Builders can also be views
-/// ```rust,no_run
+/// ```rust
+/// use too::view::{Builder, View, Ui};
+///
 /// // views must be `Debug`, builders don't have to be
 /// #[derive(Debug)]
 /// struct Foo;

src/view/debug.rs

@@ -644,7 +644,9 @@ fn evaluate<R: 'static>(
 /// Generate a pretty tree of the views (nodes) for this application
 ///
 /// Example:
-/// ```rust,no_run
+/// ```rust
+/// use too::{layout::Align2, views::fill};
+///
 /// too::view::debug::pretty_tree(|ui| {
 ///     ui.center(|ui| ui.label("hello world"));
 ///
@@ -653,10 +655,10 @@ fn evaluate<R: 'static>(
 ///     });
 ///
 ///     ui.show(fill("#F0F", [10.0, 10.0]));
-/// })
+/// });
 /// ```
 /// produces:
-/// ```text
+/// ```text,no_run
 ///                                         ┌──────────────┐
 ///                                         │ 1v1     Root │
 ///                                         ╞══════════════╡
@@ -726,7 +728,9 @@ pub fn pretty_tree<R: 'static>(app: impl FnMut(&Ui) -> R) -> TreeOutput {
 /// Generate a compact tree of the views (nodes) for this application
 ///
 /// Example:
-/// ```rust,no_run
+/// ```rust
+/// use too::{layout::Align2, views::fill};
+///
 /// too::view::debug::compact_tree(|ui| {
 ///     ui.center(|ui| ui.label("hello world"));
 ///
@@ -735,10 +739,10 @@ pub fn pretty_tree<R: 'static>(app: impl FnMut(&Ui) -> R) -> TreeOutput {
 ///     });
 ///
 ///     ui.show(fill("#F0F", [10.0, 10.0]));
-/// })
+/// });
 /// ```
 /// produces:
-/// ```text
+/// ```text,no_run
 /// Root(1v1)
 /// ├─ Aligned(2v1)
 /// │  └─ Label(3v1)
@@ -761,7 +765,9 @@ pub fn compact_tree<R: 'static>(app: impl FnMut(&Ui) -> R) -> TreeOutput {
 /// This includes the rectangles for each view
 ///
 /// Example:
-/// ```rust,no_run
+/// ```rust
+/// use too::{layout::Align2, views::fill};
+///
 /// too::view::debug::compact_tree_sizes(|ui| {
 ///     ui.center(|ui| ui.label("hello world"));
 ///
@@ -770,10 +776,10 @@ pub fn compact_tree<R: 'static>(app: impl FnMut(&Ui) -> R) -> TreeOutput {
 ///     });
 ///
 ///     ui.show(fill("#F0F", [10.0, 10.0]));
-/// })
+/// });
 /// ```
 /// produces:
-/// ```text
+/// ```text,no_run
 /// Root(1v1)         ║ x: 0  y: 0  ┊ w: 80 h: 25
 /// ├─ Aligned(2v1)   ║ x: 0  y: 0  ┊ w: 80 h: 25
 /// │  └─ Label(3v1)  ║ x: 35 y: 12 ┊ w: 11 h: 1
@@ -794,19 +800,21 @@ pub fn compact_tree_sizes<R: 'static>(app: impl FnMut(&Ui) -> R) -> TreeOutput {
 /// Generate the paint list this application would do
 ///
 /// Example:
-/// ```rust,no_run
-/// too::view::render_tree(|ui| {
+/// ```rust
+/// use too::{layout::Align2, views::fill};
+///
+/// too::view::debug::render_tree(|ui| {
 ///     ui.center(|ui| ui.label("hello world"));
 ///
 ///     ui.aligned(Align2::RIGHT_TOP, |ui| {
 ///         ui.button("click me");
 ///     });
 ///
 ///     ui.show(fill("#F0F", [10.0, 10.0]));
-/// })
+/// });
 /// ```
 /// produces:
-/// ```rust,no_run
+/// ```text,no_run
 /// ViewId(3v1): Text { rect: { x: 35, y: 12, w: 11, h: 1 }, shape: TextShape { label: "hello world", fg: Set(rgb(255, 255, 255, 255)), bg: Reuse, attribute: None } }
 /// ViewId(5v1): FillBg { rect: { x: 70, y: 0, w: 10, h: 1 }, color: rgb(77, 77, 77, 255) }
 /// ViewId(5v1): Text { rect: { x: 71, y: 0, w: 8, h: 1 }, shape: TextShape { label: "click me", fg: Set(rgb(255, 255, 255, 255)), bg: Reuse, attribute: None } }

src/view/layout.rs

@@ -26,7 +26,7 @@ impl<'a> Filterable for Layout<'a> {
 /// - return that size
 ///
 /// ## In your code:
-/// ```rust,no_run
+/// ```compile_fail
 /// let current = layout.nodes.get_current();
 /// let mut size = Size::ZERO;
 /// for &child in &current.children {

src/view/state.rs

@@ -29,7 +29,9 @@ use super::{
 /// You can have multiple state, they are built with a [`Rect`] as their constraining bounds.
 ///
 /// ## State life cycles
-/// ```rust,no_run
+/// ```compile_fail
+/// use too::view::State;
+///
 /// let mut state = State::new(Palette::default(), Animations::default());
 ///
 /// // provide a way to read events from a backend

src/view/style.rs

@@ -9,11 +9,11 @@ use crate::renderer::Rgba;
 /// ## Convention
 ///
 /// Conventional types:
-/// ```rust,no_run
+/// ```ignore
 /// struct Style;
 /// type Class = fn(&Palette) -> Style;
-/// fn class(mut self, Class) -> Self;
-/// fn style(mut self, Style) -> Self;
+/// fn class(mut self, class: Class) -> Self;
+/// fn style(mut self, style: Style) -> Self;
 /// ```
 ///
 /// 3## Description
@@ -33,7 +33,13 @@ use crate::renderer::Rgba;
 ///
 /// ### Example
 /// A simple example:
-/// ```rust,no_run
+/// ```rust
+/// use too::{
+///     layout::Axis,
+///     renderer::{Rgba, Pixel},
+///     view::{Palette, StyleKind, Builder, View, Render}
+/// };
+///
 /// #[derive(Copy, Clone, Debug)]
 /// struct MyStyle {
 ///     background: Rgba,
@@ -114,8 +120,9 @@ use crate::renderer::Rgba;
 ///         render.fill_with(Pixel::new(style.fill).bg(style.background));
 ///     }
 /// }
-///
-/// // then a user can do:
+///```
+/// Then a user can do:
+/// ```ignore
 /// // for a deferred style:
 /// ui.show(builder().class(MyStyle::hash_at));
 /// // or for a pre-computed style