beeware · freakboy3742 · Mar 24, 2024 · Mar 23, 2024 · Mar 23, 2024 · Mar 23, 2024
diff --git a/changes/2381.docs.rst → changes/2381.doc.rst b/changes/2381.docs.rst → changes/2381.doc.rst
diff --git a/changes/2463.doc.rst b/changes/2463.doc.rst
@@ -0,0 +1 @@
+The documentation landing page and some documentation sections were reorganized.
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -1,3 +1,14 @@
+div.table {
+    clear: both;
+    display: flex;
+    flex-wrap: wrap;
+    column-gap: 2rem;
+}
+
+div.table > * {
+    width: 20rem;
+}
+
 /* Draw lines around table edges. */
 table.docutils {
     border: 1px solid var(--color-background-border);

diff --git a/docs/background/community.rst b/docs/background/community.rst
@@ -0,0 +1,18 @@
+=========
+Community
+=========
+
+Toga is part of the `BeeWare suite`_. You can talk to the community through:
+
+* `@beeware@fosstodon.org on Mastodon`_
+* `Discord`_
+* The Toga `GitHub Discussions forum`_
+
+We foster a welcoming and respectful community as described in our
+`BeeWare Community Code of Conduct`_.
+
+.. _BeeWare suite: https://beeware.org/
+.. _@beeware@fosstodon.org on Mastodon: https://fosstodon.org/@beeware
+.. _Discord: https://beeware.org/bee/chat/
+.. _GitHub Discussions forum: https://github.com/beeware/toga/discussions
+.. _BeeWare Community Code of Conduct: https://beeware.org/community/behavior/
diff --git a/docs/background/index.rst b/docs/background/index.rst
@@ -8,5 +8,5 @@ Background
    :maxdepth: 2
 
    project/index
-   topics/index
+   community
    internals/index
diff --git a/docs/background/project/faq.rst b/docs/background/project/faq.rst
@@ -1,8 +1,8 @@
 .. _togas-and-yaks:
 
-========================
-Why "Toga"? Why the Yak?
-========================
+===
+FAQ
+===
 
 So... why the name Toga?
 ========================

diff --git a/docs/background/project/index.rst b/docs/background/project/index.rst
@@ -1,12 +1,12 @@
-=================
-About the project
-=================
+==========
+About Toga
+==========
 
 .. toctree::
    :maxdepth: 1
 
-   philosophy
-   faq
+   Project philosophy <philosophy>
+   FAQ <faq>
    success
    releases
    roadmap
diff --git a/docs/background/project/roadmap.rst b/docs/background/project/roadmap.rst
@@ -1,6 +1,6 @@
-========
-Road Map
-========
+===============
+Toga's Road Map
+===============
 
 Toga is a new project - we have lots of things that we'd like to do. If
 you'd like to contribute, you can provide a patch for one of these features.
@@ -20,37 +20,67 @@ Input
 
 Inputs are mechanisms for displaying and editing input provided by the user.
 
-* ``ComboBox`` - A free entry text field that provides options (e.g., text with past choices)
+Partially implemented widgets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``Table``
+
+  Mobile platforms don't provide a native "Table" widget; however, table-like
+  data could be rendered by using a :class:`~toga.DetailedList`, where the
+  title and subtitle are the "important" columns selected by the user, and
+  selecting a row on the table navigates to a sub-page showing the full row
+  detail.
 
-    - Cocoa: ``NSComboBox``
-    - GTK: ``Gtk.ComboBox.new_with_model_and_entry``
-    - iOS: ?
-    - Winforms: ``ComboBox``
-    - Android: ``Spinner``
+* ``Tree``
+
+  As with Table, mobile platforms don't provide a native "Tree" widget; however,
+  we could use a similar approach to Table.
+
+  On Windows, the native widget doesn't provide support for more than one column. This
+  means we either need to make a special case on Windows for a "simple" tree; or we need
+  to form a composite widget that pairs the scrolling of a table with a tree.
 
 * ``DateTimeInput`` - A widget for selecting a date and a time.
 
-    - Cocoa: ``NSDatePicker``
-    - GTK: `Gtk.Calendar` + ?
-    - iOS: ``UIDatePicker``
-    - Winforms: ``DateTimePicker``
-    - Android: ?
+  - Cocoa: ``NSDatePicker``
+  - GTK: ``Gtk.Calendar`` + ?
+  - iOS: ``UIDatePicker``
+
+New widgets
+^^^^^^^^^^^
+
+* ``RadioButton`` - a set of mutually exclusive options.
+
+  Functionally, the use case of "select one from a list of options" can be met with a
+  :class:`~toga.Selection`; however, from a UI design perspective, a radio button is a
+  common design pattern.
+
+  See `this issue <https://github.com/beeware/toga/issues/2225>`__ for discussion of how
+  this widget may be implemented in a way that compliments existing widgets.
+
+* ``ComboBox`` - A free entry text field that provides options (e.g., text with past choices)
+
+  - Cocoa: ``NSComboBox``
+  - GTK: ``Gtk.ComboBox.new_with_model_and_entry``
+  - iOS: ?
+  - Winforms: ``ComboBox``
+  - Android: ``Spinner``
 
 * ``ColorInput`` - A widget for selecting a color
 
-    - Cocoa: ``NSColorWell``
-    - GTK: ``Gtk.ColorButton`` or ``Gtk.ColorSelection``
-    - iOS: ?
-    - Winforms: ?
-    - Android: ?
+  - Cocoa: ``NSColorWell``
+  - GTK: ``Gtk.ColorButton`` or ``Gtk.ColorSelection``
+  - iOS: ?
+  - Winforms: ?
+  - Android: ?
 
 * ``SearchInput`` - A variant of ``TextField`` that is decorated as a search box.
 
-    - Cocoa: ``NSSearchField``
-    - GTK: ``Gtk.Entry``
-    - iOS: ``UISearchBar``?
-    - Winforms: ?
-    - Android: ?
+  - Cocoa: ``NSSearchField``
+  - GTK: ``Gtk.Entry``
+  - iOS: ``UISearchBar``?
+  - Winforms: ?
+  - Android: ?
 
 Views
 ~~~~~
@@ -60,80 +90,76 @@ usually in a read-only manner.
 
 * ``VideoView`` - Display a video
 
-    - Cocoa: ``AVPlayerView``
-    - GTK: Custom integration with ``GStreamer``
-    - iOS: ``MPMoviePlayerController``
-    - Winforms: ?
-    - Android: ?
+  - Cocoa: ``AVPlayerView``
+  - GTK: Custom integration with ``GStreamer``
+  - iOS: ``MPMoviePlayerController``
+  - Winforms: ?
+  - Android: ?
 
 * ``PDFView`` - Display a PDF document
 
-    - Cocoa: ``PDFView``
-    - GTK: ?
-    - iOS: Integration with QuickLook?
-    - Winforms: ?
-    - Android: ?
-
-* ``MapView`` - Display a map
-
-    - Cocoa: ``MKMapView``
-    - GTK: Probably a ``Webkit.WebView`` pointing at Google Maps/OpenStreetMap
-    - iOS: ``MKMapView``
-    - Winforms: ?
-    - Android: ?
-
+  - Cocoa: ``PDFView``
+  - GTK: ?
+  - iOS: Integration with QuickLook?
+  - Winforms: ?
+  - Android: ?
 
 Container widgets
 ~~~~~~~~~~~~~~~~~
 
 Containers are widgets that can contain other widgets.
 
-* ``ButtonContainer`` - A layout for a group of radio/checkbox options
-
-    - Cocoa: ``NSMatrix``, or ``NSView`` with pre-set constraints.
-    - GTK: ``Gtk.ListBox``
-    - iOS: ?
-    - Winforms: ?
-    - Android: ?
-
 * ``FormContainer`` - A layout for a "key/value" or "label/widget" form
 
-    - Cocoa: ``NSForm``, or ``NSView`` with pre-set constraints.
-    - GTK:
-    - iOS:
-    - Winforms: ?
-    - Android: ?
+  - Cocoa: ``NSForm``, or ``NSView`` with pre-set constraints.
+  - GTK:
+  - iOS:
+  - Winforms: ?
+  - Android: ?
 
 * ``NavigationContainer`` - A container view that holds a navigable tree of sub-views
 
-    Essentially a view that has a "back" button to return to the previous view
-    in a hierarchy. Example of use: Top level navigation in the macOS System
-    Preferences panel.
+  Essentially a view that has a "back" button to return to the previous view
+  in a hierarchy. Example of use: Top level navigation in the macOS System
+  Preferences panel.
 
-    - Cocoa: No native control
-    - GTK: No native control; ``Gtk.HeaderBar`` in 3.10+
-    - iOS: ``UINavigationBar`` + ``NavigationController``
-    - Winforms: ?
-    - Android: ?
+  - Cocoa: No native control
+  - GTK: No native control; ``Gtk.HeaderBar`` in 3.10+
+  - iOS: ``UINavigationBar`` + ``NavigationController``
+  - Winforms: ?
+  - Android: ?
 
-Miscellaneous
-~~~~~~~~~~~~~
+Other capabilities
+------------------
 
 One of the aims of Toga is to provide a rich, feature-driven approach to
 app development. This requires the development of APIs to support rich
 features.
 
-* Preferences - Support for saving app preferences, and visualizing them in a
+* **Preferences** - Support for saving app preferences, and visualizing them in a
   platform native way.
 
-* Notification when updates are available
+* **Notification** - A mechanism to display popup "toast"-style notifications
+
+* **System tray icons** - Presenting an icon and/or menu in the platform's system tray -
+  possibly without having a main app window at all.
+
+* **Licensing/registration** - Monetization is not a bad thing, and shouldn't be
+  mutually exclusive with open source.
+
+* **Audio** - The ability to play sound files, either once off, or on a loop.
+
+* **Cloud data access** - Traditional apps store all their files locally; however,
+  using cloud services or network resources is increasingly common, especially in
+  mobile apps. However, accessing cloud-based files can be very complicated; Toga
+  is in a position to provide a file-like API that abstracts accessing these APIs.
 
-* Easy Licensing/registration of apps - Monetization is not a bad thing, and
-  shouldn't be mutually exclusive with open source.
+* **QR code scanning** - The ability to scan QR codes and bar codes in an app, and
+  return the encoded data.
 
 Platforms
 ---------
 
-Toga currently has good support for Cocoa on macOS, GTK on Linux, Winforms on
-Windows, iOS and Android. Proof-of-concept support exists for single page web
-apps. Support for a more modern Windows API would be desirable.
+Toga currently has good support for Cocoa on macOS, GTK on Linux, Winforms on Windows,
+iOS and Android. Proof-of-concept support exists for single page web apps and consoles.
+Support for a more modern Windows API would be desirable, as would support for Qt.
diff --git a/docs/how-to/backends/android.rst b/docs/how-to/backends/android.rst
diff --git a/docs/how-to/backends/cocoa.rst b/docs/how-to/backends/cocoa.rst
diff --git a/docs/how-to/backends/gtk.rst b/docs/how-to/backends/gtk.rst
diff --git a/docs/how-to/backends/iOS.rst b/docs/how-to/backends/iOS.rst
diff --git a/docs/how-to/backends/index.rst b/docs/how-to/backends/index.rst