Repository: tauri-apps/wry (language: rust)

Issue:
Readme out of sync with library docs
The [platform-specific notes in the README](https://github.com/tauri-apps/wry?tab=readme-ov-file#platform-specific-notes) are missing a detail about `gtk::init()`, which is only covered in the library docs: https://docs.rs/wry/latest/wry/#platform-considerations. Perhaps it should also have a specific `### Unix/Linux` subsection like the README.

The Android docs appear to have some more overlap though.

Should there be a CI process to keep these in sync to make it easier to find relevant information, regardless of where this is being read?


Discussion / hints:

Fix patch:
diff --git a/README.md b/README.md
index 296be5a2a..617d30b65 100644
--- a/README.md
+++ b/README.md
@@ -7,68 +7,64 @@
 [![https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg](https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg)](https://good-labs.github.io/greater-good-affirmation)
 [![support](https://img.shields.io/badge/sponsor-Open%20Collective-blue.svg)](https://opencollective.com/tauri)
 
-Cross-platform WebView rendering library in Rust that supports all major desktop platforms like Windows, macOS, and Linux.
-
-<div align="center">
-  <a href="https://gfycat.com/needywetelk">
-    <img src="https://thumbs.gfycat.com/NeedyWetElk-size_restricted.gif">
-  </a>
-</div>
-
-## Overview
-
-WRY connects the web engine on each platform and provides easy to use and unified interface to render WebView.
-The webview requires a running event loop and a window type that implements `HasWindowHandle`,
-or a gtk container widget if you need to support X11 and Wayland.
-You can use a windowing library like `tao` or `winit`.
-
-## Usage
-
-The minimum example to create a Window and browse a website looks like following:
-
-```rust
-fn main() -> wry::Result<()> {
-  use tao::{
-    event::{Event, StartCause, WindowEvent},
-    event_loop::{ControlFlow, EventLoop},
-    window::WindowBuilder,
-  };
-  use wry::WebViewBuilder;
-
-  let event_loop = EventLoop::new();
-  let window = WindowBuilder::new()
-    .with_title("Hello World")
-    .build(&event_loop)
-    .unwrap();
-
-  let webview = WebViewBuilder::new()
-    .with_url("https://tauri.app")
-    .build(&window)?;
-
-  event_loop.run(move |event, _, control_flow| {
-    *control_flow = ControlFlow::Wait;
-
-    match event {
-      Event::NewEvents(StartCause::Init) => println!("Wry has started!"),
-      Event::WindowEvent {
-        event: WindowEvent::CloseRequested,
-        ..
-      } => *control_flow = ControlFlow::Exit,
-      _ => (),
-    }
-  });
+Cross-platform WebView rendering library in Rust that supports all major desktop platforms like Windows, macOS, Linux, Android and iOS.
+
+## Examples
+
+This example leverages the `HasWindowHandle` trait from `raw-window-handle` crate and supports Windows, macOS, iOS, Android and Linux (X11 Only).
+See the following example using `winit`.
+
+```rs
+use wry::{WebView, WebViewBuilder};
+use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
+
+#[derive(Default)]
+struct App {
+  webview_window: Option<(Window, WebView)>,
 }
-```
 
-There are also more samples under `examples`, you can enter commands like the following to try them:
+impl ApplicationHandler for App {
+  fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+    let window = event_loop.create_window(Window::default_attributes()).unwrap();
+    let webview = WebViewBuilder::new()
+      .with_url("https://tauri.app")
+      .build(&window)
+      .unwrap();
 
-```
-cargo run --example multiwindow
+    self.webview_window = Some((window, webview));
+  }
+
+  fn window_event(&mut self, _event_loop: &ActiveEventLoop, _window_id: WindowId, event: WindowEvent) {}
+}
+
+let event_loop = EventLoop::new().unwrap();
+let mut app = App::default();
+event_loop.run_app(&mut app).unwrap();
 ```
 
-For more information, please read the documentation below.
+If you also want to support Wayland too, then we recommend you use `WebViewBuilderExtUnix::new_gtk` on Linux.
+See the following example using `tao`.
 
-## [Documentation](https://docs.rs/wry)
+```rs
+use wry::WebViewBuilder;
+use tao::{window::WindowBuilder, event_loop::EventLoop};
+#[cfg(target_os = "linux")]
+use tao::platform::unix::WindowExtUnix;
+#[cfg(target_os = "linux")]
+use wry::WebViewBuilderExtUnix;
+
+let event_loop = EventLoop::new();
+let window = WindowBuilder::new().build(&event_loop).unwrap();
+
+let builder = WebViewBuilder::new().with_url("https://tauri.app");
+
+#[cfg(not(target_os = "linux"))]
+let webview = builder.build(&window).unwrap();
+#[cfg(target_os = "linux")]
+let webview = builder.build_gtk(window.gtk_window()).unwrap();
+```
+
+For more information, please read the crate [documentation](https://docs.rs/wry) .
 
 ## Platform-specific notes
 
@@ -98,40 +94,40 @@ sudo dnf install gtk3-devel webkit2gtk4.1-devel
 
 ### Nix & NixOS
 
- ```Nix
+```Nix
 # shell.nix
 
- let
-    # Unstable Channel | Rolling Release
-    pkgs = import (fetchTarball("channel:nixpkgs-unstable")) { };
-    packages = with pkgs; [
-      pkg-config
-      webkitgtk_4_1
-    ];
-  in
-  pkgs.mkShell {
-    buildInputs = packages;
-  }
- ```
+let
+   # Unstable Channel | Rolling Release
+   pkgs = import (fetchTarball("channel:nixpkgs-unstable")) { };
+   packages = with pkgs; [
+     pkg-config
+     webkitgtk_4_1
+   ];
+ in
+ pkgs.mkShell {
+   buildInputs = packages;
+ }
+```
 
- ```sh
- nix-shell shell.nix
- ```
+```sh
+nix-shell shell.nix
+```
 
 #### GUIX
 
- ```scheme
+```scheme
 ;; manifest.scm
 
- (specifications->manifest
-   '("pkg-config"                ; Helper tool used when compiling
-     "webkitgtk"                 ; Web content engine fot GTK+
-  ))
- ```
+(specifications->manifest
+  '("pkg-config"                ; Helper tool used when compiling
+    "webkitgtk"                 ; Web content engine fot GTK+
+ ))
+```
 
 ```sh
 guix shell -m manifest.scm
-````
+```
 
 ### macOS
 
diff --git a/src/lib.rs b/src/lib.rs
index 037f4a6db..a8d568ec9 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -11,12 +11,11 @@
 //! ## Examples
 //!
 //! This example leverages the [`HasWindowHandle`] and supports Windows, macOS, iOS, Android and Linux (X11 Only).
-//! See the following example using [`winit`].
+//! See the following example using [`winit`]:
 //!
 //! ```no_run
 //! # use wry::{WebViewBuilder, raw_window_handle};
 //! # use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
-//!
 //! #[derive(Default)]
 //! struct App {
 //!   window: Option<Window>,
@@ -44,7 +43,7 @@
 //! ```
 //!
 //! If you also want to support Wayland too, then we recommend you use [`WebViewBuilderExtUnix::new_gtk`] on Linux.
-//! See the following example using [`tao`].
+//! See the following example using [`tao`]:
 //!
 //! ```no_run
 //! # use wry::WebViewBuilder;
@@ -72,7 +71,6 @@
 //! ```no_run
 //! # use wry::{WebViewBuilder, raw_window_handle, Rect, dpi::*};
 //! # use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
-//!
 //! #[derive(Default)]
 //! struct App {
 //!   window: Option<Window>,
@@ -138,18 +136,21 @@
 //!
 //! ## Platform Considerations
 //!
-//! Note that on Linux, we use webkit2gtk webviews so if the windowing library doesn't support gtk (as in [`winit`])
+//! Here is the underlying web engine each platform uses, and some dependencies you might need to install.
+//!
+//! ### Linux
+//!
+//! [WebKitGTK](https://webkitgtk.org/) is used to provide webviews on Linux which requires GTK,
+//! so if the windowing library doesn't support GTK (as in [`winit`])
 //! you'll need to call [`gtk::init`] before creating the webview and then call [`gtk::main_iteration_do`] alongside
 //! your windowing library event loop.
 //!
 //! ```no_run
-//! # use wry::{WebViewBuilder, raw_window_handle};
+//! # use wry::{WebView, WebViewBuilder};
 //! # use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
-//!
 //! #[derive(Default)]
 //! struct App {
-//!   window: Option<Window>,
-//!   webview: Option<wry::WebView>,
+//!   webview_window: Option<(Window, WebView)>,
 //! }
 //!
 //! impl ApplicationHandler for App {
@@ -160,8 +161,7 @@
 //!       .build(&window)
 //!       .unwrap();
 //!
-//!     self.window = Some(window);
-//!     self.webview = Some(webview);
+//!     self.webview_window = Some((window, webview));
 //!   }
 //!
 //!   fn window_event(&mut self, _event_loop: &ActiveEventLoop, _window_id: WindowId, event: WindowEvent) {}
@@ -180,7 +180,40 @@
 //! event_loop.run_app(&mut app).unwrap();
 //! ```
 //!
-//! ## Android
+//! #### Linux Dependencies
+//!
+//! ##### Arch Linux / Manjaro:
+//!
+//! ```bash
+//! sudo pacman -S webkit2gtk-4.1
+//! ```
+//!
+//! ##### Debian / Ubuntu:
+//!
+//! ```bash
+//! sudo apt install libwebkit2gtk-4.1-dev
+//! ```
+//!
+//! ##### Fedora
+//!
+//! ```bash
+//! sudo dnf install gtk3-devel webkit2gtk4.1-devel
+//! ```
+//!
+//! ### macOS
+//!
+//! WebKit is native on macOS so everything should be fine.
+//!
+//! If you are cross-compiling for macOS using [osxcross](https://github.com/tpoechtrager/osxcross) and encounter a runtime panic like `Class with name WKWebViewConfiguration could not be found` it's possible that `WebKit.framework` has not been linked correctly, to fix this set the `RUSTFLAGS` environment variable:
+//!
+//! ```bash
+//! RUSTFLAGS="-l framework=WebKit" cargo build --target=x86_64-apple-darwin --release
+//! ```
+//! ### Windows
+//!
+//! WebView2 provided by Microsoft Edge Chromium is used. So wry supports Windows 7, 8, 10 and 11.
+//!
+//! ### Android
 //!
 //! In order for `wry` to be able to create webviews on Android, there is a few requirements that your application needs to uphold:
 //! 1. You need to set a few environment variables that will be used to generate the necessary kotlin


Test patch: