Merge redundant examples

The following 4 examples all demonstrate various aspects of using `argparse` for command argument processing and have been merged into a single comprehensive example called `argparse_example.py`:
- arg_decorators.py
- decorator_example.py
- arg_print.py
- subcommands.py

`first_app.py` and `initialization.py` had a lot of overlap in demonstrating basic features of cmd2. I combined them into a single `getting_started.py` example

Author: tleonhardt

.github/CONTRIBUTING.md

@@ -329,7 +329,7 @@ environment is set up and working properly.
 You can also run the example app and see a prompt that says "(Cmd)" running the command:
 
 ```sh
-$ uv run examples/example.py
+$ uv run examples/getting_started.py
 ```
 
 You can type `help` to get help or `quit` to quit. If you see that, then congratulations – you're

cmd2/cmd2.py

@@ -10,7 +10,7 @@
 Settable environment parameters
 Parsing commands with `argparse` argument parsers (flags)
 Redirection to file or paste buffer (clipboard) with > or >>
-Easy transcript-based testing of applications (see examples/example.py)
+Easy transcript-based testing of applications (see examples/transcript_example.py)
 Bash-style ``select`` available
 
 Note, if self.stdout is different than sys.stdout, then redirection with > and |

cmd2/transcript.py

@@ -34,7 +34,7 @@ class Cmd2TestCase(unittest.TestCase):
     that will execute the commands in a transcript file and expect the
     results shown.
 
-    See example.py
+    See transcript_example.py
     """
 
     cmdapp: Optional['Cmd'] = None

docs/examples/first_app.md renamed to docs/examples/getting_started.md

@@ -1,6 +1,6 @@
-# First Application
+# Getting Started
 
-Here's a quick walkthrough of a simple application which demonstrates 8 features of `cmd2`:
+Here's a quick walkthrough of a simple application which demonstrates 10 features of `cmd2`:
 
 - [Settings](../features/settings.md)
 - [Commands](../features/commands.md)
@@ -14,17 +14,17 @@ Here's a quick walkthrough of a simple application which demonstrates 8 features
 If you don't want to type as we go, here is the complete source (you can click to expand and then
 click the **Copy** button in the top-right):
 
-??? example
+!!! example "getting_started.py"
 
     ```py
     {%
-        include "../../examples/first_app.py"
+        include "../../examples/getting_started.py"
     %}
     ```
 
 ## Basic Application
 
-First we need to create a new `cmd2` application. Create a new file `first_app.py` with the
+First we need to create a new `cmd2` application. Create a new file `getting_started.py` with the
 following contents:
 
 ```py
@@ -47,7 +47,7 @@ We have a new class `FirstApp` which is a subclass of [cmd2.Cmd][]. When we tell
 file like this:
 
 ```shell
-$ python first_app.py
+$ python getting_started.py
 ```
 
 it creates an instance of our class, and calls the `cmd2.Cmd.cmdloop` method. This method accepts
@@ -77,7 +77,7 @@ In that initializer, the first thing to do is to make sure we initialize `cmd2`.
 run the script, and enter the `set` command to see the settings, like this:
 
 ```shell
-$ python first_app.py
+$ python getting_started.py
 (Cmd) set
 ```
 
@@ -88,8 +88,8 @@ you will see our `maxrepeats` setting show up with it's default value of `3`.
 Now we will create our first command, called `speak` which will echo back whatever we tell it to
 say. We are going to use an [argument processor](../features/argument_processing.md) so the `speak`
 command can shout and talk piglatin. We will also use some built in methods for
-[generating output](../features/generating_output.md). Add this code to `first_app.py`, so that the
-`speak_parser` attribute and the `do_speak()` method are part of the `CmdLineApp()` class:
+[generating output](../features/generating_output.md). Add this code to `getting_started.py`, so
+that the `speak_parser` attribute and the `do_speak()` method are part of the `CmdLineApp()` class:
 
 ```py
 speak_parser = cmd2.Cmd2ArgumentParser()

docs/examples/index.md

@@ -2,7 +2,7 @@
 
 <!--intro-start-->
 
-- [First Application](first_app.md)
+- [Getting Started](getting_started.md)
 - [Alternate Event Loops](alternate_event_loops.md)
 - [List of cmd2 examples](examples.md)
 

docs/features/argument_processing.md

@@ -14,10 +14,10 @@ following for you:
 
 These features are all provided by the `@with_argparser` decorator which is importable from `cmd2`.
 
-See the either the [argprint](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_print.py)
-or [decorator](https://github.com/python-cmd2/cmd2/blob/main/examples/decorator_example.py) example
-to learn more about how to use the various `cmd2` argument processing decorators in your `cmd2`
-applications.
+See the
+[argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py)
+example to learn more about how to use the various `cmd2` argument processing decorators in your
+`cmd2` applications.
 
 `cmd2` provides the following [decorators](../api/decorators.md) for assisting with parsing
 arguments passed to commands:
@@ -286,8 +286,9 @@ argparse sub-parsers.
 You may add multiple layers of subcommands for your command. `cmd2` will automatically traverse and
 tab complete subcommands for all commands using argparse.
 
-See the [subcommands](https://github.com/python-cmd2/cmd2/blob/main/examples/subcommands.py) example
-to learn more about how to use subcommands in your `cmd2` application.
+See the
+[argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py)
+example to learn more about how to use subcommands in your `cmd2` application.
 
 ## Argparse Extensions
 

docs/features/initialization.md

@@ -2,11 +2,11 @@
 
 Here is a basic example `cmd2` application which demonstrates many capabilities which you may wish to utilize while initializing the app:
 
-!!! example "examples/initialization.py"
+!!! example "examples/getting_started.py"
 
     ```py
     {%
-        include "../../examples/initialization.py"
+        include "../../examples/getting_started.py"
     %}
     ```
 

docs/features/os.md

@@ -69,23 +69,23 @@ user to enter commands, which are then executed by your program.
 You may want to execute commands in your program without prompting the user for any input. There are
 several ways you might accomplish this task. The easiest one is to pipe commands and their arguments
 into your program via standard input. You don't need to do anything to your program in order to use
-this technique. Here's a demonstration using the `examples/example.py` included in the source code
-of `cmd2`:
+this technique. Here's a demonstration using the `examples/transcript_example.py` included in the
+source code of `cmd2`:
 
-    $ echo "speak -p some words" | python examples/example.py
+    $ echo "speak -p some words" | python examples/transcript_example.py
     omesay ordsway
 
 Using this same approach you could create a text file containing the commands you would like to run,
 one command per line in the file. Say your file was called `somecmds.txt`. To run the commands in
 the text file using your `cmd2` program (from a Windows command prompt):
 
-    c:\cmd2> type somecmds.txt | python.exe examples/example.py
+    c:\cmd2> type somecmds.txt | python.exe examples/transcript_example.py
     omesay ordsway
 
 By default, `cmd2` programs also look for commands pass as arguments from the operating system
 shell, and execute those commands before entering the command loop:
 
-    $ python examples/example.py help
+    $ python examples/transcript_example.py help
 
     Documented commands (use 'help -v' for verbose/'help <topic>' for details):
     ===========================================================================
@@ -99,8 +99,8 @@ example, you might have a command inside your `cmd2` program which itself accept
 maybe even option strings. Say you wanted to run the `speak` command from the operating system
 shell, but have it say it in pig latin:
 
-    $ python example/example.py speak -p hello there
-    python example.py speak -p hello there
+    $ python example/transcript_example.py speak -p hello there
+    python transcript_example.py speak -p hello there
     usage: speak [-h] [-p] [-s] [-r REPEAT] words [words ...]
     speak: error: the following arguments are required: words
     *** Unknown syntax: -p
@@ -122,7 +122,7 @@ Check the source code of this example, especially the `main()` function, to see
 Alternatively you can simply wrap the command plus arguments in quotes (either single or double
 quotes):
 
-    $ python example/example.py "speak -p hello there"
+    $ python example/transcript_example.py "speak -p hello there"
     ellohay heretay
     (Cmd)
 
@@ -148,6 +148,6 @@ quits while returning an exit code:
 
 Here is another example using `quit`:
 
-    $ python example/example.py "speak -p hello there" quit
+    $ python example/transcript_example.py "speak -p hello there" quit
     ellohay heretay
     $

docs/features/prompt.md

@@ -6,7 +6,7 @@
 
 This prompt can be configured by setting the `cmd2.Cmd.prompt` instance attribute. This contains the
 string which should be printed as a prompt for user input. See the
-[Initialization](https://github.com/python-cmd2/cmd2/blob/main/examples/initialization.py) example
+[getting_started](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) example
 for the simple use case of statically setting the prompt.
 
 ## Continuation Prompt
@@ -15,7 +15,7 @@ When a user types a [Multiline Command](./multiline_commands.md) it may span mor
 input. The prompt for the first line of input is specified by the `cmd2.Cmd.prompt` instance
 attribute. The prompt for subsequent lines of input is defined by the `cmd2.Cmd.continuation_prompt`
 attribute.See the
-[Initialization](https://github.com/python-cmd2/cmd2/blob/main/examples/initialization.py) example
+[getting_started](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) example
 for a demonstration of customizing the continuation prompt.
 
 ## Updating the prompt

docs/features/startup_commands.md

@@ -16,7 +16,7 @@ program. `cmd2` interprets each argument as a separate command, so you should en
 in quotation marks if it is more than a one-word command. You can use either single or double quotes
 for this purpose.
 
-    $ python examples/example.py "say hello" "say Gracie" quit
+    $ python examples/transcript_example.py "say hello" "say Gracie" quit
     hello
     Gracie