Merge pull request beeware#1807 from oddbookworm/document-external-hooks

Added docs for externally supported entry points

changes/1807.doc.rst

@@ -0,0 +1 @@
+Documentation on Briefcase's plug-in interfaces was added.

changes/1807.feature.rst

@@ -0,0 +1 @@
+The new project wizard now includes links to known third-party GUI bootstraps.

docs/reference/commands/new.rst

@@ -49,3 +49,31 @@ The expected keys are specified by the cookiecutter template being used to
 create the new project. Therefore, the set of possible keys is not listed here
 but should be expected to remain consistent for any specific version of
 Briefcase; with version changes, though, the keys may change.
+
+Third-party Bootstraps
+======================
+
+When you run new project wizard, you are asked to select a GUI toolkit. Briefcase
+includes bootstraps for `Toga <https://toga.readthedocs.io>`__ (BeeWare's cross-platform
+GUI framework), `PySide6 <https://wiki.qt.io/Qt_for_Python>`__ (Python bindings for the
+Qt GUI toolkit) and `Pygame <https://www.pygame.org/news>`__ (a common Python game
+development toolkit), as well as an "empty" bootstrap that doesn't include any GUI code.
+However, Briefcase provides a :ref:`plug-in interface <bootstrap-interface>` that allows
+GUI toolkits to provide a their own bootstrap implementation.
+
+The following third-party bootstraps are known to exist:
+
+=================================== ============== ===================================================
+Bootstrap                           Package name   Description
+=================================== ============== ===================================================
+`PursuedPyBear <https://ppb.dev>`__ ``ppb``        "Unbearably fun game development". A game toolkit
+                                                   with a focus on being education friendly and
+                                                   exposing an idiomatic Python interface.
+----------------------------------- -------------- ---------------------------------------------------
+`Pygame-ce <https://pyga.me>`__     ``pygame-ce``  A fork of pygame, the classic library for making
+                                                   games in Python.
+=================================== ============== ===================================================
+
+To add a third-party bootstrap, ``pip install`` the named package into the virtual
+environment that contains Briefcase, then run ``briefcase new``. The new bootstrap
+option should be added to the list of GUI toolkits.

docs/reference/index.rst

@@ -14,3 +14,4 @@ This is the technical reference for public APIs provided by Briefcase.
    configuration
    commands/index
    platforms/index
+   plugins

docs/reference/plugins.rst

@@ -0,0 +1,70 @@
+========
+Plug-ins
+========
+
+Briefcase ships with support for a range of platforms, output formats and GUI toolkits.
+Internally, these features are implemented using a plug-in interface; as a result, it is
+possible for third-party projects to add their own features to Briefcase by implementing
+plug-ins that satisfy those interfaces.
+
+Each plug-in is defined using an `entry point
+<https://packaging.python.org/en/latest/specifications/entry-points/>`__ definition in
+``pyproject.toml``.
+
+.. _bootstrap-interface:
+
+``briefcase.bootstraps``
+========================
+
+The Briefcase :doc:`new project wizard </reference/commands/new>` asks users to select a
+GUI toolkit. The option selected at this step alters the content of the code generated
+by the wizard, generating framework-specific requirements, system packages, and stub
+code for a new application using that GUI framework. These additions are configured
+using a ``briefcase.bootstrap`` plug-in.
+
+To add a custom ``briefcase.bootstrap`` plug-in, add a
+``[project.entry-points."briefcase.platforms"]`` section to your ``pyproject.toml``
+file; each name/value pair under that section will be interpreted as a bootstrap. The
+name of each bootstrap setting is the label that will be surfaced to the user in the
+wizard. The value is a string identifying a class that implements the
+``briefcase.bootstraps.base.BaseGuiBootstrap`` abstract base class.
+
+For example, the Toga bootstrap is implemented using the following configuration::
+
+    [project.entry-points."briefcase.bootstraps"]
+    Toga = "briefcase.bootstraps.toga:TogaGuiBootstrap"
+
+``briefcase.platforms`` and ``briefcase.formats.*``
+===================================================
+
+Each command implemented by Briefcase is specialized by a platform and output format.
+This implementation is defined using a pair of plug-ins - a ``briefcase.platforms``
+definition describing a platform, and a ``briefcase.format.<platform>`` definition that
+defines the output formats for that platform.
+
+The ``briefcase.platforms`` entry point defines the existence of a platform. Each name
+in this section is name of a platform that can be used when invoking Briefcase commands.
+The value is a fully-qualified Python module name that must defines a single constant
+``DEFAULT_OUTPUT_FORMAT``.
+
+Each platform name is then incorporated into the name of a separate ``format`` entry
+point. Each entry in the ``format`` section for a platform is the name of an output
+format that can be used when invoking Briefcase commands. The value is a fully-qualified
+Python module name that defines 7 symbols:
+
+* ``create`` - a subclass of ``briefcase.commands.create.CreateCommand``
+* ``update`` - a subclass of ``briefcase.commands.create.UpdateCommand``
+* ``open`` - a subclass of ``briefcase.commands.create.OpenCommand``
+* ``build`` - a subclass of ``briefcase.commands.create.BuildCommand``
+* ``run`` - a subclass of ``briefcase.commands.create.RunCommand``
+* ``package`` - a subclass of ``briefcase.commands.create.PackageCommand``
+* ``publish`` - a subclass of ``briefcase.commands.create.PublishCommand``
+
+For example, the definition for the macOS Xcode output format is controlled by the
+following::
+
+    [project.entry-points."briefcase.platforms"]
+    macOS = "briefcase.platforms.macOS"
+
+    [project.entry-points."briefcase.formats.macOS"]
+    xcode = "briefcase.platforms.macOS.xcode"

docs/spelling_wordlist

@@ -11,6 +11,7 @@ backported
 BeeWare
 Bugfix
 Bugfixes
+ce
 checkmarks
 codebase
 Cookiecutter
@@ -66,6 +67,7 @@ proxied
 Proxied
 proxying
 px
+pygame
 Pygame
 Pyodide
 PyScript
@@ -87,6 +89,7 @@ submodule
 subprocesses
 tl
 toml
+toolkits
 towncrier
 tox
 TTY

src/briefcase/commands/new.py

@@ -621,7 +621,13 @@ def build_gui_context(
                 bootstrap_override = reverse_lookup[bootstraps[bootstrap_override]]
 
         selected_bootstrap = self.select_option(
-            intro="What GUI toolkit do you want to use for this project?",
+            intro=(
+                "What GUI toolkit do you want to use for this project?\n"
+                "\n"
+                "Additional GUI bootstraps are available; visit "
+                "https://beeware.org/bee/briefcase-bootstraps "
+                "for a full list of known GUI bootstraps."
+            ),
             variable="GUI Framework",
             default=None,
             options=bootstrap_options.keys(),