Docs: Add Building a CLI Application Tutorial

changes/1947.doc.rst

@@ -0,0 +1 @@
+A tutorial for writing command-line apps was added.

docs/tutorial/cli-apps.rst

@@ -0,0 +1,292 @@
+==========================================
+Building a CLI application with Briefcase
+==========================================
+
+Overview
+---------
+
+In this tutorial, you'll learn how to build and package a Command Line Interface
+(CLI) application for distribution on Windows, macOS, and Linux using Briefcase.
+
+We're going to assume you've got an environment set up like you did in the
+`Hello, World! tutorial <https://docs.beeware.org/en/latest/tutorial/tutorial-0.html>`_.
+
+
+Bootstrap a new project
+------------------------
+
+Let's start our first Briefcase CLI project! We're going to use the Briefcase
+``new`` command to create an application called **Hello CLI**.
+Run the following from your command prompt:
+
+.. tabs::
+
+  .. group-tab:: macOS
+
+    .. code-block:: console
+
+      (venv) $ briefcase new
+      Let's build a new Briefcase app!
+      ...
+
+  .. group-tab:: Linux
+
+    .. code-block:: console
+
+      (venv) $ briefcase new
+      Let's build a new Briefcase app!
+      ...
+
+  .. group-tab:: Windows
+
+    .. code-block:: doscon
+
+      (venv) C:\...>briefcase new
+      Let's build a new Briefcase app!
+      ...
+
+Briefcase will ask us for some details of our new application. For the
+purposes of this tutorial, use the following:
+
+* **Formal Name** - Accept the default value: ``Hello CLI``.
+
+* **App Name** - Accept the default value: ``hello-cli``.
+
+* **Bundle** - If you own your own domain, enter that domain in reversed order.
+  (For example, if you own the domain "cupcakes.com", enter ``com.cupcakes``
+  as the bundle). If you don't own your own domain, accept the default bundle
+  (``com.example``).
+
+* **Project Name** - Accept the default value: ``Hello CLI``.
+
+* **Description** - Accept the default value (or, if you want to be really
+  creative, come up with your own description!)
+
+* **Author** - Enter your own name here.
+
+* **Author's email** - Enter your own email address. This will be used in the
+  configuration file, in help text, and anywhere that an email is required
+  when submitting the app to an app store.
+
+* **URL** - The URL of the landing page for your application. Again, if you own
+  your own domain, enter a URL at that domain (including the ``https://``).
+  Otherwise, just accept the default URL (``https://example.com/hello-cli``).
+  This URL doesn't need to actually exist (for now); it will only be used if
+  you publish your application to an app store.
+
+* **License** - Accept the default license (BSD). This won't affect
+  anything about the operation of the tutorial, though - so if you have
+  particularly strong feelings about license choice, feel free to choose
+  another license.
+
+* **GUI framework** - Enter ``4`` to select the **Console** GUI framework. This
+  will create a project that is designed to run in a terminal window.
+
+Briefcase will then generate a project skeleton for you to use.
+If you've followed this tutorial so far, and accepted the defaults as described,
+your file system should look something like::
+
+    tutorial/
+    ├── venv/
+    │   └── ...
+    └── hello-cli/
+        ├── CHANGELOG
+        ├── LICENSE
+        ├── pyproject.toml
+        ├── README.rst
+        ├── src/
+        │   └── hello_cli/
+        │       ├── app.py
+        │       ├── __init__.py
+        │       ├── __main__.py
+        │       └── resources/
+        │           └── README
+        └── tests/
+            ├── hello_cli.py
+            ├── __init__.py
+            └── test_app.py
+
+The ``src`` folder contains all the code for the application, the
+``tests`` folder contains an initial test suite, and the ``pyproject.toml`` file
+describes how to package the application for distribution. If you open
+``pyproject.toml`` in an editor, you'll see the configuration details you just
+provided to Briefcase.
+
+Now that we have a stub application, we can use Briefcase to run the
+application.
+
+
+Running the application in developer mode
+------------------------------------------
+
+To run the application in developer (or ``dev``) mode, navigate to the project
+directory ``hello-cli`` and run the following command:
+
+.. tabs::
+
+  .. group-tab:: macOS
+
+    .. code-block:: console
+
+      (venv) $ cd hello-cli
+      (venv) $ briefcase dev
+
+      [hello-cli] Installing requirements...
+      ...
+
+      [hello-cli] Starting in dev mode...
+      ===========================================================================
+      Hello, World.
+      ===========================================================================
+
+  .. group-tab:: Linux
+
+    .. code-block:: console
+
+      (venv) $ cd hello-cli
+      (venv) $ briefcase dev
+
+      [hello-cli] Installing requirements...
+      ...
+
+      [hello-cli] Starting in dev mode...
+      ===========================================================================
+      Hello, World.
+      ===========================================================================
+
+  .. group-tab:: Windows
+
+    .. code-block:: doscon
+
+      (venv) C:\...>cd hello-cli
+      (venv) C:\...>briefcase dev
+
+      [hello-cli] Installing requirements...
+      ...
+
+      [hello-cli] Starting in dev mode...
+      ===========================================================================
+      Hello, World.
+      ===========================================================================
+
+The application will start in the terminal window. You should see a message
+that says "Hello, World.".
+
+Now you are ready to start building your CLI application!
+
+
+Making it interesting
+----------------------
+
+Right now the ``app.py`` file contains a simple ``print`` statement that
+prints "Hello, World.". Let's use :any:`argparse` to make it more interesting.
+
+Replace the contents of ``src/hello_cli/app.py`` with the following code:
+
+.. code-block:: python
+
+    import argparse
+
+    def main():
+        parser = argparse.ArgumentParser(
+            prog="hello-cli",
+            usage="%(prog)s [options] name",
+            description="A simple command line application.",
+            add_help=True
+        )
+        parser.add_argument("name", help="Your name")
+        parser.add_argument("-v", "--version", action="version", version="%(prog)s 1.0")
+        args = parser.parse_args()
+        print(f'Hello, {args.name}!')
+
+Let's look in detail at what has changed.
+
+1. We import the  :any:`argparse` module.
+2. We define a new function called ``main`` that will contain the logic for
+   our application.
+3. We create an instance of :any:`argparse.ArgumentParser` and pass in some arguments:
+    * ``prog``: The name of the program (in this case, ``hello-cli``).
+    * ``usage``: The usage message that will be displayed when the user runs
+      the program with the ``-h`` or ``--help`` flag.
+    * ``description``: A description of the program.
+    * ``add_help``: Whether to add a ``-h`` or ``--help`` flag to the program.
+4. We add two arguments to the parser:
+    * ``name``: A positional argument that takes the user's name.
+    * ``version``: An optional argument that prints the version of the program.
+5. We parse the arguments using ``parser.parse_args()``.
+6. We print a message that greets the user by name.
+
+
+Now that we've made these changes we can see what they look like by starting
+the application again. As before, we'll use developer mode:
+
+.. tabs::
+
+  .. group-tab:: macOS
+
+    .. code-block:: console
+
+      (venv) $ briefcase dev
+
+  .. group-tab:: Linux
+
+    .. code-block:: console
+
+      (venv) $ briefcase dev
+
+  .. group-tab:: Windows
+
+    .. code-block:: doscon
+
+      (venv) C:\...>briefcase dev
+
+When you run the application, you should see the following output:
+
+.. code-block:: console
+
+    [hello-cli] Starting in dev mode...
+    ===========================================================================
+    usage: hello-cli [options] name
+    hello-cli: error: the following arguments are required: name
+
+To pass arguments to the application, we will use the the following briefcase
+command ``-- ARGS ...``. Let's run the application again, this time with a name:
+
+.. tabs::
+
+  .. group-tab:: macOS
+
+    .. code-block:: console
+
+      (venv) $ briefcase dev -- John
+
+  .. group-tab:: Linux
+
+    .. code-block:: console
+
+      (venv) $ briefcase dev -- John
+
+  .. group-tab:: Windows
+
+    .. code-block:: doscon
+
+      (venv) C:\...>briefcase dev -- John
+
+Now you should see the following output:
+
+.. code-block:: console
+
+    [hello-cli] Starting in dev mode...
+    ===========================================================================
+    Hello, John!
+
+Congratulations! You've just built a simple command line application using
+Briefcase.
+
+Next steps
+----------
+
+So far we have been running the application in developer mode.
+To distribute the application, you will need to package it for distribution.
+For more information, see the
+`Tutorial 3 - Packaging for distribution documentation <https://docs.beeware.org/en/latest/tutorial/tutorial-3.html>`_.

docs/tutorial/index.rst

@@ -13,3 +13,15 @@ through the process of building a native Python application from scratch.
 
 Once you've done that tutorial, the :doc:`Briefcase How-To Guides
 <../how-to/index>` provide details on performing specific tasks with Briefcase.
+
+Additional Topics
+-----------------
+
+If you're looking for a more advanced tutorials,
+you might be interested in these topics:
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   cli-apps