From 4e3251c300638b326e4c49c746651b6f65cc8026 Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Sat, 2 Jan 2021 11:59:20 +0100 Subject: [PATCH] Improve ecosystem documentation and add changelogs for epi and eframe --- CHANGELOG.md | 2 +- eframe/CHANGELOG.md | 10 ++++++++++ eframe/README.md | 4 ++-- eframe/src/lib.rs | 14 +++++++------- egui/src/lib.rs | 6 +++--- egui_glium/src/lib.rs | 6 ++++++ egui_web/src/lib.rs | 6 ++++++ epi/CHANGELOG.md | 10 ++++++++++ epi/README.md | 6 ++---- epi/src/lib.rs | 13 +++++-------- 10 files changed, 52 insertions(+), 25 deletions(-) create mode 100644 eframe/CHANGELOG.md create mode 100644 epi/CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 349f46cd..586e426a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to the Egui crate will be documented in this file. -NOTE: `egui_web` and `egui_glium` has their own changelogs! +NOTE: `epi`, `eframe`, `egui_web` and `egui_glium` has their own changelogs! The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). diff --git a/eframe/CHANGELOG.md b/eframe/CHANGELOG.md new file mode 100644 index 00000000..58b61ef3 --- /dev/null +++ b/eframe/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog for eframe + +All notable changes to the `eframe` crate. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + + +## Unreleased + +* Initial release of eframe diff --git a/eframe/README.md b/eframe/README.md index c9cef9c4..45b22d57 100644 --- a/eframe/README.md +++ b/eframe/README.md @@ -2,6 +2,6 @@ This aims to be the entry-level crate if you want to write an Egui App. -`eframe` calls into your code (it is a framework) and supports web apps (via `egui_web`) and native apps (via `egui_glium`). +`eframe` calls into your code (it is a framework) and supports web apps (via [`egui_web`](https://crates.io/crates/egui_web)) and native apps (via [`egui_glium`](https://crates.io/crates/egui_glium)). -`eframe` is a very thin crate that re-exports `egui`, `epi` and thin wrappers over the backends. +`eframe` is a very thin crate that re-exports [`egui`](https://crates.io/crates/egui), [`epi`](https://crates.io/crates/epi) and thin wrappers over the backends. diff --git a/eframe/src/lib.rs b/eframe/src/lib.rs index 63752f09..b89fcff5 100644 --- a/eframe/src/lib.rs +++ b/eframe/src/lib.rs @@ -1,11 +1,11 @@ -//! Backend-agnostic interface for writing apps using Egui. +//! eframe - the Egui Framework crate //! -//! Egui is a GUI library, which can be plugged in to e.g. a game engine. +//! You write your application code for [`epi`] (implementing [`epi::App`]) and then +//! use eframe to either compile and run it natively, or compile it as a web app. //! -//! This crate provides a common interface for programming an app, using Egui, -//! so you can then easily plug it in to a backend such as `egui_web` or `egui_glium`. +//! To get started, look at . //! -//! This crate is primarily used by the `egui_web` and `egui_glium` crates. +//! eframe is implemented using [`egui_web`](https://docs.rs/egui_web) and [`egui_glium`](https://docs.rs/egui_glium). #![forbid(unsafe_code)] #![cfg_attr(not(debug_assertions), deny(warnings))] // Forbid warnings in release builds @@ -47,8 +47,8 @@ pub fn start_web(canvas_id: &str, app: Box) -> Result<(), wasm_bin // ---------------------------------------------------------------------------- // When compiling natively -/// Call from main as `eframe::run_native(Box::new(MyEguiApp::default()))` +/// Call from `fn main` like this: `eframe::run_native(Box::new(MyEguiApp::default()))` #[cfg(not(target_arch = "wasm32"))] -pub fn run_native(app: Box) { +pub fn run_native(app: Box) -> ! { egui_glium::run(app) } diff --git a/egui/src/lib.rs b/egui/src/lib.rs index 1970f07e..2e3373fd 100644 --- a/egui/src/lib.rs +++ b/egui/src/lib.rs @@ -1,9 +1,9 @@ //! Egui core library //! -//! To get started with Egui, you can use one of the available integrations -//! such as [`egui_web`](https://crates.io/crates/egui_web) or [`egui_glium`](https://crates.io/crates/egui_glium). +//! To quickly get started with Egui, you can take a look at [`egui_template`](https://github.com/emilk/egui_template) +//! which uses [`eframe`](https://docs.rs/eframe). //! -//! Whatever you use, you need an [`CtxRef`] (by convention referred to by `ctx`). +//! To create a GUI using Egui you first need a [`CtxRef`] (by convention referred to by `ctx`). //! Use one of [`SidePanel`], [`TopPanel`], [`CentralPanel`], [`Window`] or [`Area`] to //! get access to an [`Ui`] where you can put widgets. For example: //! diff --git a/egui_glium/src/lib.rs b/egui_glium/src/lib.rs index ca69532d..9f1e7fdf 100644 --- a/egui_glium/src/lib.rs +++ b/egui_glium/src/lib.rs @@ -1,3 +1,9 @@ +//! [`egui`] bindings for [`glium`](https://github.com/glium/glium). +//! +//! This library is an [`epi`] backend. +//! +//! If you are writing an app, you may want to look at [`eframe`](https://docs.rs/eframe) instead. + #![forbid(unsafe_code)] #![cfg_attr(not(debug_assertions), deny(warnings))] // Forbid warnings in release builds #![warn(clippy::all)] diff --git a/egui_web/src/lib.rs b/egui_web/src/lib.rs index 5e8da801..e6f31ecb 100644 --- a/egui_web/src/lib.rs +++ b/egui_web/src/lib.rs @@ -1,3 +1,9 @@ +//! [`egui`] bindings for web apps (compiling to WASM). +//! +//! This library is an [`epi`] backend. +//! +//! If you are writing an app, you may want to look at [`eframe`](https://docs.rs/eframe) instead. + #![forbid(unsafe_code)] #![cfg_attr(not(debug_assertions), deny(warnings))] // Forbid warnings in release builds #![warn(clippy::all)] diff --git a/epi/CHANGELOG.md b/epi/CHANGELOG.md new file mode 100644 index 00000000..02020075 --- /dev/null +++ b/epi/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog for epi + +All notable changes to the `epi` crate. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + + +## Unreleased + +* Initial release of epi diff --git a/epi/README.md b/epi/README.md index 9c2e85d9..82fa4325 100644 --- a/epi/README.md +++ b/epi/README.md @@ -1,7 +1,5 @@ # Egui app Programming Interface -Backend-agnostic interface for writing apps using Egui. +Backend-agnostic interface for writing apps using [`egui`](https://crates.io/crates/egui) (a platform agnostic GUI library). -Egui is a GUI library, which can be plugged in to e.g. a game engine. - -This crate provides a common interface for programming an app, using Egui, so you can then easily plug it in to a backend such as `egui_web` or `egui_glium`. +This crate provides a common interface for programming an app using Egui, which can then be easily plugged into [`egui_frame`](https://crates.io/crates/egui_frame) (which in a wrapper over [`egui_web`](https://crates.io/crates/egui_web) or [`egui_glium`](https://crates.io/crates/egui_glium)). diff --git a/epi/src/lib.rs b/epi/src/lib.rs index 6d61ea8a..f3bbe4f6 100644 --- a/epi/src/lib.rs +++ b/epi/src/lib.rs @@ -1,13 +1,10 @@ //! Backend-agnostic interface for writing apps using [`egui`]. //! -//! [`egui`] is a GUI library, which can be plugged in to e.g. a game engine. +//! `epi` provides interfaces for window management, serialization and http requests. +//! An app written for `epi` can then be plugged into [`eframe`](https://docs.rs/eframe), +//! the Egui framework crate. //! -//! Start by looking at the [`App`] trait, and implement [`App::ui`]. -//! -//! This crate provides a common interface for programming an app, using Egui, -//! so you can then easily plug it in to a backend such as `egui_web` or `egui_glium`. -//! -//! This crate is primarily used by the `egui_web` and `egui_glium` crates. +//! Start by looking at the [`App`] trait, and implement [`App::update`]. #![cfg_attr(not(debug_assertions), deny(warnings))] // Forbid warnings in release builds #![forbid(unsafe_code)] @@ -329,7 +326,7 @@ pub mod backend { } impl<'a> FrameBuilder<'a> { - /// Wrap us in a [`Frame`] to send to [`App::ui`]. + /// Wrap us in a [`Frame`] to send to [`App::update`]. pub fn build(self) -> Frame<'a> { Frame(self) }