Finish making a detailed pass through the existing documentation

Author: tleonhardt

docs/doc_conventions.md

@@ -36,7 +36,7 @@ In Markdown all indenting is significant. Use 4 spaces per indenting level.
 
 ## Wrapping
 
-Hard wrap all text so that line lengths are no greater than 120 characters. It makes everything
+Hard wrap all text so that line lengths are no greater than 100 characters. It makes everything
 easier when editing documentation, and has no impact on reading documentation because we render to
 html.
 
@@ -75,9 +75,13 @@ When using `mkdocstrings`, it must be preceded by a blank line before and after,
 
 ### Links to API Reference
 
-To reference a method or function, do the following:
+To reference a class, method, or function, do the following use block quotes around it followed by
+empty block quotes. So to reference `cmd2.Cmd`, you using `[cmd2.Cmd][]`.
 
-TODO: Figure out how to do this
+If you want to change the name to use something shorter than the full namespace resolution you can
+put the full path in the 2nd set of block quotes instead of leaving it empty and put the shorter
+name in the one on the left. So you could also use `[Cmd][cmd2.Cmd]` to link to the API
+documentation for `cmd2.Cmd`.
 
 ## Referencing cmd2
 

docs/examples/alternate_event_loops.md

@@ -44,25 +44,25 @@ if __name__ == '__main__':
     app.postloop()
 ```
 
-The `cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via
-`cmd2.Cmd.onecmd_plus_hooks()`.
+The [cmd2.Cmd.runcmds_plus_hooks][] method runs multiple commands where each single command is
+executed via [cmd2.Cmd.onecmd_plus_hooks][].
 
-The `cmd2.Cmd.onecmd_plus_hooks()` method will do the following to execute a single command in a
+The [cmd2.Cmd.onecmd_plus_hooks][] method will do the following to execute a single command in a
 normal fashion:
 
-1.  Parse user input into a `cmd2.Statement` object
-1.  Call methods registered with `cmd2.Cmd.register_postparsing_hook()`
+1.  Parse user input into a [cmd2.Statement][] object
+1.  Call methods registered with [cmd2.Cmd.register_postparsing_hook][]
 1.  Redirect output, if user asked for it and it's allowed
 1.  Start timer
-1.  Call methods registered with `cmd2.Cmd.register_precmd_hook`
-1.  Call `cmd2.Cmd.precmd` - for backwards compatibility with `cmd.Cmd`
+1.  Call methods registered with [cmd2.Cmd.register_precmd_hook][]
+1.  Call [cmd2.Cmd.precmd][] - for backwards compatibility with `cmd`
 1.  Add statement to [History](../features/history.md)
 1.  Call `do_command` method
-1.  Call methods registered with `cmd2.Cmd.register_postcmd_hook()`
-1.  Call `cmd2.Cmd.postcmd` - for backwards compatibility with `cmd.Cmd`
+1.  Call methods registered with [cmd2.Cmd.register_postcmd_hook][]
+1.  Call [cmd2.Cmd.postcmd][] - for backwards compatibility with `cmd`
 1.  Stop timer and display the elapsed time
 1.  Stop redirecting output if it was redirected
-1.  Call methods registered with `cmd2.Cmd.register_cmdfinalization_hook()`
+1.  Call methods registered with [cmd2.Cmd.register_cmdfinalization_hook][]
 
 Running in this fashion enables the ability to integrate with an external event loop. However, how
 to integrate with any specific event loop is beyond the scope of this documentation. Please note

docs/examples/getting_started.md

@@ -1,6 +1,8 @@
 # Getting Started
 
-Here's a quick walkthrough of a simple application which demonstrates 10 features of `cmd2`:
+Here's a quick walkthrough of a the simple
+[getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
+example application which demonstrates many features of `cmd2`:
 
 - [Settings](../features/settings.md)
 - [Commands](../features/commands.md)
@@ -29,36 +31,36 @@ following contents:
 
 ```py
 #!/usr/bin/env python
-"""A simple cmd2 application."""
+"""A basic cmd2 application."""
 import cmd2
 
 
-class FirstApp(cmd2.Cmd):
-    """A simple cmd2 application."""
+class BasicApp(cmd2.Cmd):
+    """Cmd2 application to demonstrate many common features."""
 
 
 if __name__ == '__main__':
     import sys
-    c = FirstApp()
-    sys.exit(c.cmdloop())
+    app = BasicApp()
+    sys.exit(app.cmdloop())
 ```
 
-We have a new class `FirstApp` which is a subclass of [cmd2.Cmd][]. When we tell python to run our
+We have a new class `BasicApp` which is a subclass of [cmd2.Cmd][]. When we tell Python to run our
 file like this:
 
 ```shell
 $ python getting_started.py
 ```
 
-it creates an instance of our class, and calls the `cmd2.Cmd.cmdloop` method. This method accepts
-user input and runs commands based on that input. Because we subclassed `cmd2.Cmd`, our new app
-already has a bunch of features built in.
+The application creates an instance of our class, and calls the [cmd2.Cmd.cmdloop][] method. This
+method accepts user input and runs commands based on that input. Because we subclassed `cmd2.Cmd`,
+our new app already has a bunch of features built in.
 
 Congratulations, you have a working `cmd2` app. You can run it, and then type `quit` to exit.
 
 ## Create a New Setting
 
-Before we create our first command, we are going to add a setting to this app. `cmd2` includes
+Before we create our first command, we are going to add a new setting to this app. `cmd2` includes
 robust support for [Settings](../features/settings.md). You configure settings during object
 initialization, so we need to add an initializer to our class:
 
@@ -89,7 +91,7 @@ Now we will create our first command, called `speak` which will echo back whatev
 say. We are going to use an [argument processor](../features/argument_processing.md) so the `speak`
 command can shout and talk pig latin. We will also use some built in methods for
 [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 `FirstApp()` class:
+that the `speak_parser` attribute and the `do_speak()` method are part of the `BasicApp()` class:
 
 ```py
 speak_parser = cmd2.Cmd2ArgumentParser()

docs/features/multiline_commands.md

@@ -1,10 +1,10 @@
 # Multiline Commands
 
 Command input may span multiple lines for the commands whose names are listed in the
-`multiline_commands` argument to `cmd2.Cmd.__init__()`. These commands will be executed only after
-the user has entered a _terminator_. By default, the command terminator is `;`; specifying the
-`terminators` optional argument to `cmd2.Cmd.__init__()` allows different terminators. A blank line
-is _always_ considered a command terminator (cannot be overridden).
+`multiline_commands` argument to [cmd2.Cmd.\_\_init\_\_][cmd2.Cmd.__init__]. These commands will be
+executed only after the user has entered a _terminator_. By default, the command terminator is `;`.
+Specifying the `terminators` optional argument to `cmd2.Cmd.__init__()` allows different
+terminators. A blank line is _always_ considered a command terminator (cannot be overridden).
 
 In multiline commands, output redirection characters like `>` and `|` are part of the command
 arguments unless they appear after the terminator.
@@ -14,7 +14,7 @@ arguments unless they appear after the terminator.
 When a user types a **Multiline Command** it may span more than one line of input. The prompt for
 the first line of input is specified by the [cmd2.Cmd.prompt][] instance attribute - see
 [Customizing the Prompt](./prompt.md#customizing-the-prompt). The prompt for subsequent lines of
-input is defined by the `cmd2.Cmd.continuation_prompt` attribute.
+input is defined by the [cmd2.Cmd.continuation_prompt][] attribute.
 
 ## Use cases
 

docs/features/os.md

@@ -15,8 +15,14 @@ get a `!` shortcut for `shell`, which allows you to type:
 
     (Cmd) !ls -al
 
-NOTE: `cmd2` provides user-friendly tab completion throughout the process of running a shell
-command - first for the shell command name itself, and then for file paths in the argument section.
+!!! note
+
+    `cmd2` provides user-friendly tab completion throughout the process of running a shell command -
+    first for the shell command name itself, and then for file paths in the argument section.
+
+    However, a `cmd2` application effectively **becomes** the shell, so if you have _extra_ shell
+    completion configured for your particular shell such as `bash`, `zsh`, `fish`, etc. then this
+    will not be available within `cmd2`.
 
 ## Editors
 
@@ -36,16 +42,18 @@ system.
 
 ## Terminal pagers
 
-Output of any command can be displayed one page at a time using the `cmd2.Cmd.ppaged` method.
+Output of any command can be displayed one page at a time using the [cmd2.Cmd.ppaged][] method.
 
 Alternatively, a terminal pager can be invoked directly using the ability to run shell commands with
 the `!` shortcut like so:
 
     (Cmd) !less foo.txt
 
-NOTE: Once you are in a terminal pager, that program temporarily has control of your terminal,
-**NOT** `cmd2`. Typically you can use either the arrow keys or `<PageUp>`/`<PageDown>` keys to
-scroll around or type `q` to quit the pager and return control to your `cmd2` application.
+!!! warning
+
+    Once you are in a terminal pager, that program temporarily has control of your terminal,
+    **NOT** `cmd2`. Typically you can use either the arrow keys or `<PageUp>`/`<PageDown>` keys to
+    scroll around or type `q` to quit the pager and return control to your `cmd2` application.
 
 ## Exit codes
 
@@ -87,10 +95,10 @@ shell, and execute those commands before entering the command loop:
 
     $ python examples/transcript_example.py help
 
-    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
-    ===========================================================================
-    alias  help     macro   orate  quit          run_script  set    shortcuts
-    edit   history  mumble  py     run_pyscript  say         shell  speak
+    Documented Commands
+    ───────────────────
+    alias  help     macro   orate  run_pyscript  say  shell      speak
+    edit   history  mumble  quit   run_script    set  shortcuts
 
     (Cmd)
 
@@ -111,8 +119,9 @@ shell, but have it say it in pig latin:
 Uh-oh, that's not what we wanted. `cmd2` treated `-p`, `hello`, and `there` as commands, which don't
 exist in that program, thus the syntax errors.
 
-There is an easy way around this, which is demonstrated in `examples/cmd_as_argument.py`. By setting
-`allow_cli_args=False` you can do your own argument parsing of the command line:
+There is an easy way around this, which is demonstrated in
+[cmd_as_argument.py](https://github.com/python-cmd2/cmd2/blob/main/examples/cmd_as_argument.py)
+example. By setting `allow_cli_args=False` you can do your own argument parsing of the command line:
 
     $ python examples/cmd_as_argument.py speak -p hello there
     ellohay heretay

docs/features/packaging.md

@@ -16,7 +16,8 @@ using idiomatic Python packaging tools such as [pip](https://pip.pypa.io/) or
 [uv](https://github.com/astral-sh/uv).
 
 Small tweaks on this process can allow you to publish to private PyPI mirrors such as one hosted on
-[AWS CodeArtifact](https://aws.amazon.com/codeartifact/).
+[AWS CodeArtifact](https://aws.amazon.com/codeartifact/) or a private
+[Artifactory](https://jfrog.com/artifactory/) server.
 
 ## Packaging your application in a container using Docker
 
@@ -33,26 +34,18 @@ This convenient blog post will show you
 For developers wishing to package a `cmd2` application into a single binary image or compressed
 file, we can recommend all of the following based on personal and professional experience:
 
+- [Nuitka](https://github.com/Nuitka/Nuitka)
+    - Nuitka is a Python compiler written in Python
+    - You feed it your Python app, it does a lot of clever things, and spits out an executable or
+      extension module
+    - Particularly convenient if you have IP you wish to protect by obfuscating the Python source
+      code behind your application
 - [PyInstaller](https://www.pyinstaller.org)
     - Freeze (package) Python programs into stand-alone executables
     - PyInstaller bundles a Python application and all its dependencies into a single package
     - The user can run the packaged app without installing a Python interpreter or any modules
-- [Nuitka](https://nuitka.net)
-    - Nuitka is a Python compiler written in Python
-    - You feed it your Python app, it does a lot of clever things, and spits out an executable or
-      extension module
-    - This can be particularly convenient if you wish to obfuscate the Python source code behind
-      your application
-- [Conda Constructor](https://github.com/conda/constructor)
-    - Allows you to create a custom Python distro based on
-      [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
 - [PyOxidizer](https://github.com/indygreg/PyOxidizer)
-    - PyOxidizer is a utility for producing binaries that embed Python
-    - PyOxidizer is capable of producing a single file executable - with a copy of Python and all
-      its dependencies statically linked and all resources embedded in the executable
+    - A modern Python application packaging and distribution tool implemented in Rust
+    - A utility for producing binaries that embed Python and all of your dependencies
     - You can copy a single executable file to another machine and run a Python application
       contained within. It just works.
-
-!!! warning
-
-    We haven't personally tested PyOxidizer with `cmd2` applications like everything else on this page, though we have heard good things about it

docs/features/plugins.md

@@ -6,7 +6,7 @@ extend basic `cmd2` functionality and can be used by multiple applications.
 There are many ways to add functionality to `cmd2` using a plugin. Most plugins will be implemented
 as a mixin. A mixin is a class that encapsulates and injects code into another class. Developers who
 use a plugin in their `cmd2` project will inject the plugin's code into their subclass of
-`cmd2.Cmd`.
+[cmd2.Cmd][].
 
 ## Mixin and Initialization
 
@@ -38,15 +38,17 @@ class Example(cmd2_myplugin.MyPlugin, cmd2.Cmd):
         # all plugins have initialized
 ```
 
-Note how the plugin must be inherited (or mixed in) before `cmd2.Cmd`. This is required for two
-reasons:
+!!! warning
 
-- The `cmd.Cmd.__init__` method in the Python standard library does not call `super().__init__()`.
-  Because of this oversight, if you don't inherit from `MyPlugin` first, the `MyPlugin.__init__()`
-  method will never be called.
-- You may want your plugin to be able to override methods from `cmd2.Cmd`. If you mixin the plugin
-  after `cmd2.Cmd`, the Python method resolution order will call [cmd2.Cmd][] methods before it
-  calls those in your plugin.
+    The plugin must be inherited (or mixed in) before `cmd2.Cmd`. This is required for two
+    reasons:
+
+    - The `cmd.Cmd.__init__` method in the Python standard library does not call `super().__init__()`.
+    Because of this oversight, if you don't inherit from `MyPlugin` first, the `MyPlugin.__init__()`
+    method will never be called.
+    - You may want your plugin to be able to override methods from `cmd2.Cmd`. If you mixin the plugin
+    after `cmd2.Cmd`, the Python method resolution order will call [cmd2.Cmd][] methods before it
+    calls those in your plugin.
 
 ## Add commands
 
@@ -77,7 +79,7 @@ class MyPlugin:
         self.add_settable(cmd2.Settable('mysetting', str, 'short help message for mysetting', self))
 ```
 
-You can hide settings from the user by calling `cmd2.Cmd.remove_settable`. See
+You can hide settings from the user by calling [cmd2.Cmd.remove_settable][]. See
 [Settings](./settings.md) for more information.
 
 ## Decorators
@@ -97,8 +99,9 @@ Hooks are a much better approach.
 ## Hooks
 
 Plugins can register hook methods, which are called by [cmd2.Cmd][] during various points in the
-application and command processing lifecycle. Plugins should not override any of the deprecated hook
-methods, instead they should register their hooks as described in the [Hooks](./hooks.md) section.
+application and command processing lifecycle. Plugins should not override any of the `cmd` base
+class hook methods, instead they should register their hooks as described in the [Hooks](./hooks.md)
+section.
 
 You should name your hooks so that they begin with the name of your plugin. Hook methods get mixed
 into the `cmd2` application and this naming convention helps avoid unintentional method overriding.
@@ -134,4 +137,5 @@ will know what's available.
 
 ## Examples
 
-See <https://github.com/python-cmd2/cmd2-plugin-template> for more info.
+See [cmd2 Plugin Template](https://github.com/python-cmd2/cmd2/tree/main/plugins/template) for more
+info.

docs/features/prompt.md

@@ -4,35 +4,35 @@
 
 ## Customizing the Prompt
 
-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
-[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.
+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
+[getting_started.py](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
 
 When a user types a [Multiline Command](./multiline_commands.md) it may span more than one line of
 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
-[getting_started](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) example
-for a demonstration of customizing the continuation prompt.
+[getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
+example for a demonstration of customizing the continuation prompt.
 
 ## Updating the prompt
 
 If you wish to update the prompt between commands, you can do so using one of the
 [Application Lifecycle Hooks](./hooks.md#application-lifecycle-hooks) such as a
 [Postcommand hook](./hooks.md#postcommand-hooks). See
-[PythonScripting](https://github.com/python-cmd2/cmd2/blob/main/examples/python_scripting.py) for an
-example of dynamically updating the prompt.
+[python_scripting.py](https://github.com/python-cmd2/cmd2/blob/main/examples/python_scripting.py)
+for an example of dynamically updating the prompt.
 
 ## Asynchronous Feedback
 
 `cmd2` provides these functions to provide asynchronous feedback to the user without interfering
 with the command line. This means the feedback is provided to the user when they are still entering
 text at the prompt. To use this functionality, the application must be running in a terminal that
-supports VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support
-these.
+supports [VT100](https://en.wikipedia.org/wiki/VT100) control characters and `readline`. Linux, Mac,
+and Windows 10 and greater all support these.
 
 ::: cmd2.Cmd.async_alert
 
@@ -49,5 +49,5 @@ Windows 10 and greater all support these.
 ::: cmd2.Cmd.set_window_title
 
 The easiest way to understand these functions is to see the
-[AsyncPrinting](https://github.com/python-cmd2/cmd2/blob/main/examples/async_printing.py) example
-for a demonstration.
+[async_printing.py](https://github.com/python-cmd2/cmd2/blob/main/examples/async_printing.py)
+example for a demonstration.

docs/features/redirection.md

@@ -58,7 +58,9 @@ output of that to a file called _output.txt_.
 
 ## Limitations of Redirection
 
-Some limitations apply to redirection and piping within `cmd2` applications:
+!!! warning
 
-- Can only pipe to shell commands, not other `cmd2` application commands
-- **stdout** gets redirected/piped, **stderr** does not
+    Some limitations apply to redirection and piping within `cmd2` applications:
+
+    - Can only pipe to shell commands, not other `cmd2` application commands
+    - **stdout** gets redirected/piped, **stderr** does not