Restructure docs landing page and some ordering.

beeware · Mar 23, 2024 · f8bb7bf · f8bb7bf
1 parent 89f18a0
commit f8bb7bf
Show file tree

Hide file tree

Showing 30 changed files with 148 additions and 125 deletions.
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/how-to/backends/android.rst → docs/background/backends/android.rst b/docs/how-to/backends/android.rst → docs/background/backends/android.rst
diff --git a/docs/how-to/backends/cocoa.rst → docs/background/backends/cocoa.rst b/docs/how-to/backends/cocoa.rst → docs/background/backends/cocoa.rst
diff --git a/docs/how-to/backends/gtk.rst → docs/background/backends/gtk.rst b/docs/how-to/backends/gtk.rst → docs/background/backends/gtk.rst
diff --git a/docs/how-to/backends/iOS.rst → docs/background/backends/iOS.rst b/docs/how-to/backends/iOS.rst → docs/background/backends/iOS.rst
diff --git a/docs/how-to/backends/index.rst → docs/background/backends/index.rst b/docs/how-to/backends/index.rst → docs/background/backends/index.rst
diff --git a/docs/how-to/backends/textual.rst → docs/background/backends/textual.rst b/docs/how-to/backends/textual.rst → docs/background/backends/textual.rst
diff --git a/docs/how-to/backends/web.rst → docs/background/backends/web.rst b/docs/how-to/backends/web.rst → docs/background/backends/web.rst
diff --git a/docs/how-to/backends/winforms.rst → docs/background/backends/winforms.rst b/docs/how-to/backends/winforms.rst → docs/background/backends/winforms.rst
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:
+
+* `@[email protected] 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/
+.. _@[email protected] 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,6 @@ Background
    :maxdepth: 2
 
    project/index
-   topics/index
+   community
+   backends/index
    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,39 @@
-=================
-About the project
-=================
+==========
+About Toga
+==========
+
+Toga is a Python native, OS native, cross platform GUI toolkit. Toga consists of a
+library of base components with a shared interface to simplify platform-agnostic GUI
+development.
+
+Toga is available on macOS, Windows, Linux (GTK), Android, iOS, for
+single-page web apps, and console apps.
+
+.. tabs::
+
+  .. group-tab:: macOS
+
+    .. figure:: /images/toga-demo-cocoa.png
+       :align: center
+       :width: 450px
+
+  .. group-tab:: Linux
+
+    .. figure:: /images/toga-demo-gtk.png
+       :align: center
+       :width: 450px
+
+  .. group-tab:: Windows
+
+    .. figure:: /images/toga-demo-winforms.png
+       :align: center
+       :width: 450px
 
 .. 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.
@@ -33,8 +33,6 @@ Inputs are mechanisms for displaying and editing input provided by the user.
     - Cocoa: ``NSDatePicker``
     - GTK: `Gtk.Calendar` + ?
     - iOS: ``UIDatePicker``
-    - Winforms: ``DateTimePicker``
-    - Android: ?
 
 * ``ColorInput`` - A widget for selecting a color
 
@@ -74,28 +72,11 @@ usually in a read-only manner.
     - Winforms: ?
     - Android: ?
 
-* ``MapView`` - Display a map
-
-    - Cocoa: ``MKMapView``
-    - GTK: Probably a ``Webkit.WebView`` pointing at Google Maps/OpenStreetMap
-    - iOS: ``MKMapView``
-    - 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.
@@ -136,4 +117,4 @@ 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.
+apps and consoles. Support for a more modern Windows API would be desirable.
diff --git a/docs/how-to/contribute-code.rst → docs/how-to/contribute/code.rst b/docs/how-to/contribute-code.rst → docs/how-to/contribute/code.rst
@@ -1,8 +1,8 @@
 .. _contribute:
 
-==============================
-How to contribute code to Toga
-==============================
+=========================
+Contributing code to Toga
+=========================
 
 If you experience problems with Toga, `log them on GitHub`_. If you want to
 contribute code, please `fork the code`_ and `submit a pull request`_.
@@ -429,10 +429,9 @@ does nothing but reproduce the problem) can be a huge help.
 Contribute improvements to documentation
 ----------------------------------------
 
-We've got a :doc:`separate contribution guide <./contribute-docs>` for
-documentation contributions. This covers how to set up your development
-environment to build Toga's documentation, and separate ideas for what to work
-on.
+We've got a :doc:`separate contribution guide <./docs>` for documentation contributions.
+This covers how to set up your development environment to build Toga's documentation,
+and separate ideas for what to work on.
 
 Implement a platform native widget
 ----------------------------------

diff --git a/docs/how-to/contribute-docs.rst → docs/how-to/contribute/docs.rst b/docs/how-to/contribute-docs.rst → docs/how-to/contribute/docs.rst
diff --git a/docs/how-to/contribute/index.rst b/docs/how-to/contribute/index.rst
@@ -0,0 +1,13 @@
+====================
+Contributing to Toga
+====================
+
+Toga is an open source project, and actively encourages community contributions. The
+following guides will help you get started contributing to Toga.
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   code
+   docs
diff --git a/docs/how-to/get-started.rst b/docs/how-to/get-started.rst
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
@@ -13,8 +13,6 @@ stand alone.
    :maxdepth: 2
    :glob:
 
-   Get started <get-started>
-   Contribute code to Toga <contribute-code>
-   Contribute documentation to Toga <contribute-docs>
-   backends/index
+   topics/index
+   contribute/index
    internal/index
diff --git a/docs/background/topics/data-sources.rst → docs/how-to/topics/data-sources.rst b/docs/background/topics/data-sources.rst → docs/how-to/topics/data-sources.rst
diff --git a/docs/background/topics/index.rst → docs/how-to/topics/index.rst b/docs/background/topics/index.rst → docs/how-to/topics/index.rst
diff --git a/docs/background/topics/layout.rst → docs/how-to/topics/layout.rst b/docs/background/topics/layout.rst → docs/how-to/topics/layout.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,81 +6,57 @@ Toga is a Python native, OS native, cross platform GUI toolkit. Toga consists of
 library of base components with a shared interface to simplify platform-agnostic GUI
 development.
 
-Toga is available on macOS, Windows, Linux (GTK), Android, iOS, and for
-single-page web apps.
+Toga is available on macOS, Windows, Linux (GTK), Android, iOS, for
+single-page web apps, and console apps.
 
-.. tabs::
+.. raw:: html
 
-  .. group-tab:: macOS
-
-    .. figure:: /images/toga-demo-cocoa.png
-       :align: center
-       :width: 450px
-
-  .. group-tab:: Linux
-
-    .. figure:: /images/toga-demo-gtk.png
-       :align: center
-       :width: 450px
-
-  .. group-tab:: Windows
-
-    .. figure:: /images/toga-demo-winforms.png
-       :align: center
-       :width: 450px
-
-
-.. rst-class::  row
-
-Table of contents
-=================
+  <div class="table">
 
 :ref:`Tutorial <tutorial>`
 --------------------------
 
-Get started with a hands-on introduction to Toga for beginners.
+* :doc:`A quick Toga demonstration <tutorial/get-started>`
+* :doc:`A hands-on introduction to Toga </tutorial/index>`
+
+:ref:`Reference <reference>`
+----------------------------
+
+* :doc:`API reference <reference/api/index>`
+* :doc:`Toga's platform support <reference/platforms/index>`
+* :doc:`Widget support by platform <reference/widgets_by_platform>`
+* :doc:`Managing style with Toga <reference/style/index>`
+* :doc:`Toga's plugin interfaces <reference/plugins/index>`
 
 :ref:`How-to guides <how-to>`
 -----------------------------
 
-Guides and recipes for common problems and tasks.
+* :doc:`Topic guides </how-to/topics/index>`
+* :doc:`Contribute to Toga <how-to/contribute/index>`
+* :doc:`Internal Toga processes <how-to/internal/index>`
 
 :ref:`Background <background>`
 ------------------------------
 
-Explanation and discussion of key topics and concepts.
-
-:ref:`Reference <reference>`
-----------------------------
-
-Technical reference - commands, modules, classes, methods.
+* :doc:`Learn more about Toga </background/project/index>`
+* :doc:`Contacting the BeeWare community </background/community>`
+* :doc:`How Toga's backends are implemented </background/backends/index>`
+* :doc:`Toga's architecture and other internals </background/internals/index>`
 
-Community
-=========
 
-Toga is part of the `BeeWare suite`_. You can talk to the community through:
-
-* `@[email protected] on Mastodon`_
-* `Discord`_
-* The Toga `Github Discussions forum`_
+.. toctree::
 
-We foster a welcoming and respectful community as described in our
-`BeeWare Community Code of Conduct`_.
+.. raw:: html
 
-.. _BeeWare suite: https://beeware.org/
-.. _@[email protected] 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/
+  </div>
 
 
 .. toctree::
    :maxdepth: 2
    :hidden:
    :titlesonly:
 
-
    tutorial/index
-   how-to/index
    reference/index
+   how-to/index
    background/index
diff --git a/docs/reference/api/resources/sources/list_source.rst b/docs/reference/api/resources/sources/list_source.rst
@@ -8,7 +8,7 @@ Usage
 
 Data sources are abstractions that allow you to define the data being managed by your
 application independent of the GUI representation of that data. For details on the use
-of data sources, see the :doc:`background guide </background/topics/data-sources>`.
+of data sources, see the :doc:`topic guide </how-to/topics/data-sources>`.
 
 ListSource is an implementation of an ordered list of data. When a ListSource is
 created, it is given a list of ``accessors`` - these are the attributes that all items

diff --git a/docs/reference/api/resources/sources/source.rst b/docs/reference/api/resources/sources/source.rst
@@ -8,7 +8,7 @@ Usage
 
 Data sources are abstractions that allow you to define the data being managed by your
 application independent of the GUI representation of that data. For details on the use
-of data sources, see the :doc:`background guide </background/topics/data-sources>`.
+of data sources, see the :doc:`topic guide </how-to/topics/data-sources>`.
 
 Source isn't useful on its own; it is a base class for data source implementations. It
 is used by ListSource, TreeSource and ValueSource, but it can also be used by custom

diff --git a/docs/reference/api/resources/sources/tree_source.rst b/docs/reference/api/resources/sources/tree_source.rst
@@ -8,7 +8,7 @@ Usage
 
 Data sources are abstractions that allow you to define the data being managed by your
 application independent of the GUI representation of that data. For details on the use
-of data sources, see the :doc:`background guide </background/topics/data-sources>`.
+of data sources, see the :doc:`topic guide </how-to/topics/data-sources>`.
 
 TreeSource is an implementation of an ordered hierarchical tree of values. When a
 TreeSource is created, it is given a list of ``accessors`` - these are the attributes

diff --git a/docs/reference/api/resources/sources/value_source.rst b/docs/reference/api/resources/sources/value_source.rst
@@ -8,7 +8,7 @@ Usage
 
 Data sources are abstractions that allow you to define the data being managed by your
 application independent of the GUI representation of that data. For details on the use
-of data sources, see the :doc:`background guide </background/topics/data-sources>`.
+of data sources, see the :doc:`topic guide </how-to/topics/data-sources>`.
 
 ValueSource is an wrapper around a single atomic value.
 

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -7,8 +7,8 @@ Reference
 .. toctree::
    :maxdepth: 1
 
+   api/index
    platforms/index
    widgets_by_platform
-   api/index
    style/index
    plugins/index