beeware · freakboy3742 · May 1, 2024 · May 1, 2024 · May 1, 2024 · May 1, 2024
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -208,7 +208,7 @@ jobs:
           pre-command: |
             sudo apt update -y
             sudo apt install -y --no-install-recommends \
-              blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0
+              blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.1
 
             # Start Virtual X server
             echo "Start X server..."

diff --git a/changes/2544.doc.rst b/changes/2544.doc.rst
@@ -0,0 +1 @@
+An explicit system requirements section was added to the documentation for widgets that require the installation of additional system components.
diff --git a/docs/reference/api/containers/optioncontainer.rst b/docs/reference/api/containers/optioncontainer.rst
@@ -132,6 +132,13 @@ item, you can specify an item using:
       # Delete the pasta tab
       del container.content[pasta_tab]
 
+System requirements
+-------------------
+
+* Using OptionContainer on Android requires the Material package in your project's
+  Gradle dependencies. Ensure your app declares a dependency on
+  ``com.google.android.material:material:1.11.0`` or later.
+
 Notes
 -----
 

diff --git a/docs/reference/api/widgets/mapview.rst b/docs/reference/api/widgets/mapview.rst
@@ -95,6 +95,30 @@ updated and removed at runtime:
 Pins can respond to being pressed. When a pin is pressed, the map generates an
 ``on_select`` event, which receives the pin as an argument.
 
+.. _mapview-system-requires:
+
+System requirements
+-------------------
+
+* Using MapView on Windows 10 requires that your users have installed the `Edge
+  WebView2 Evergreen Runtime
+  <https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download>`__.
+  This is installed by default on Windows 11.
+
+* Using MapView on Linux requires that the user has installed the system packages
+  for WebKit2, plus the GObject Introspection bindings for WebKit2. The name of
+  the system package required is distribution dependent:
+
+  - Ubuntu 18.04, 20.04; Debian 11: ``gir1.2-webkit2-4.0``
+  - Ubuntu 22.04+; Debian 12+: ``gir1.2-webkit2-4.1``
+  - Fedora: ``webkit2gtk4.1``
+  - Arch/Manjaro: ``webkit2gtk-4.1``
+  - FreeBSD: ``webkit2-gtk3``
+
+* Using MapView on Android requires the OSMDroid package in your project's Gradle
+  dependencies. Ensure your app declares a dependency on
+  ``org.osmdroid:osmdroid-android:6.1.0`` or later.
+
 Notes
 -----
 
@@ -107,18 +131,6 @@ Notes
   `OpenStreetMap Foundation <https://osmfoundation.org>`__, as their work is what allows
   Toga to provide map content on these platforms.
 
-* Using MapView on Android requires the OSMDroid package to be added your project's
-  Gradle dependencies. Ensure your app declares a dependency on
-  ``org.osmdroid:osmdroid-android:6.1.0`` or later.
-
-* Using MapView on Windows 10 requires that your users have installed the `Edge
-  WebView2 Evergreen Runtime
-  <https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download>`__.
-  This is installed by default on Windows 11.
-
-* Using MapView on Linux requires that the user has installed the system packages
-  for WebKit2, plus the GObject Introspection bindings for WebKit2.
-
 * On macOS and iOS, MapView will not repeat map tiles if the viewable area at the given
   zoom level is bigger than the entire world. A zoom to a very low level will be clipped
   to the lowest level that allows displaying the map without repeating tiles.

diff --git a/docs/reference/api/widgets/webview.rst b/docs/reference/api/widgets/webview.rst
@@ -61,20 +61,33 @@ Usage
     # Load static HTML content into the wevbiew.
     webview.set_content("https://example.com", "<html>...</html>")
 
-Notes
------
 
-* Due to app security restrictions, WebView can only display ``http://`` and
-  ``https://`` URLs, not ``file://`` URLs. To serve local file content, run a
-  web server on ``localhost`` using a background thread.
+.. _webview-system-requires:
+
+System requirements
+-------------------
 
 * Using WebView on Windows 10 requires that your users have installed the `Edge
   WebView2 Evergreen Runtime
   <https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download>`__.
   This is installed by default on Windows 11.
 
 * Using WebView on Linux requires that the user has installed the system packages
-  for WebKit2, plus the GObject Introspection bindings for WebKit2.
+  for WebKit2, plus the GObject Introspection bindings for WebKit2. The name of
+  the system package required is distribution dependent:
+
+  - Ubuntu 18.04, 20.04; Debian 11: ``gir1.2-webkit2-4.0``
+  - Ubuntu 22.04+; Debian 12+: ``gir1.2-webkit2-4.1``
+  - Fedora: ``webkit2gtk4.1``
+  - Arch/Manjaro: ``webkit2gtk-4.1``
+  - FreeBSD: ``webkit2-gtk3``
+
+Notes
+-----
+
+* Due to app security restrictions, WebView can only display ``http://`` and
+  ``https://`` URLs, not ``file://`` URLs. To serve local file content, run a
+  web server on ``localhost`` using a background thread.
 
 * On macOS 13.3 (Ventura) and later, the content inspector for your app can be opened by
   running Safari, `enabling the developer tools

diff --git a/docs/reference/platforms/unix-prerequisites.rst b/docs/reference/platforms/unix-prerequisites.rst
@@ -2,34 +2,39 @@ These instructions are different on almost every version of Linux and Unix; here
 some of the common alternatives:
 
 ..
-    The package list should be the same as in ci.yml, and the BeeWare tutorial.
+    The package list should be the same as in ci.yml, and the BeeWare tutorial
+    (CI will also have WebView requirements)
 
-**Ubuntu 18.04+ / Debian 10+**
+**Ubuntu 18.04+ / Debian 11+**
 
 .. code-block:: console
 
     (venv) $ sudo apt update
-    (venv) $ sudo apt install pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0 libcanberra-gtk3-module
+    (venv) $ sudo apt install pkg-config python3-dev libgirepository1.0-dev libcairo2-dev libcanberra-gtk3-module
 
 **Fedora**
 
 .. code-block:: console
 
-    (venv) $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-gobject-devel webkit2gtk3 libcanberra-gtk3
+    (venv) $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-gobject-devel libcanberra-gtk3
 
 **Arch / Manjaro**
 
 .. code-block:: console
 
-    (venv) $ sudo pacman -Syu git pkgconf gobject-introspection cairo webkit2gtk libcanberra
+    (venv) $ sudo pacman -Syu git pkgconf gobject-introspection cairo libcanberra
 
 **FreeBSD**
 
 .. code-block:: console
 
     (venv) $ sudo pkg update
-    (venv) $ sudo pkg install gobject-introspection cairo webkit2-gtk3 libcanberra-gtk3
+    (venv) $ sudo pkg install gobject-introspection cairo libcanberra-gtk3
 
 If you're not using one of these, you'll need to work out how to install the developer
 libraries for ``python3``, ``cairo``, and ``gobject-introspection`` (and please let us
 know so we can improve this documentation!)
+
+Some widgets (most notably, the :ref:`WebView <webview-system-requires>` and
+:ref:`MapView <mapview-system-requires>` widgets) have additional system requirements.
+See the documentation of those widgets for details.
diff --git a/gtk/src/toga_gtk/libs/gtk.py b/gtk/src/toga_gtk/libs/gtk.py
@@ -16,7 +16,7 @@
 try:
     try:
         gi.require_version("WebKit2", "4.1")
-    except ValueError:
+    except ValueError:  # pragma: no cover
         gi.require_version("WebKit2", "4.0")
     from gi.repository import WebKit2  # noqa: F401
 except (ImportError, ValueError):  # pragma: no cover

diff --git a/gtk/src/toga_gtk/widgets/mapview.py b/gtk/src/toga_gtk/widgets/mapview.py
@@ -71,7 +71,9 @@ def create(self):
         if WebKit2 is None:  # pragma: no cover
             raise RuntimeError(
                 "Unable to import WebKit2. Ensure that the system package "
-                "providing Webkit2 and its GTK bindings have been installed."
+                "providing WebKit2 and its GTK bindings have been installed. "
+                "See https://toga.readthedocs.io/en/stable/reference/api/widgets/mapview.html#system-requirements "
+                "for details."
             )
 
         self.native = WebKit2.WebView()

diff --git a/gtk/src/toga_gtk/widgets/webview.py b/gtk/src/toga_gtk/widgets/webview.py
@@ -13,7 +13,9 @@ def create(self):
         if WebKit2 is None:  # pragma: no cover
             raise RuntimeError(
                 "Unable to import WebKit2. Ensure that the system package "
-                "providing Webkit2 and its GTK bindings have been installed."
+                "providing WebKit2 and its GTK bindings have been installed. "
+                "See https://toga.readthedocs.io/en/stable/reference/api/widgets/webview.html#system-requirements "
+                "for details."
             )
 
         self.native = WebKit2.WebView()