doc updates

Author: bckohan

README.rst

@@ -91,6 +91,10 @@ Installation
             'django_typer',
         ]
 
+   *You only need to install django_typer as an app if you want to use the shellcompletion command
+   to enable tab-completion or if you would like django-typer to install `rich traceback rendering 
+   <https://django-typer.readthedocs.io/en/latest/howto.html#configure-rich-stack-traces>`_
+   for you - which it does by default if rich is also installed.*
 
 Basic Example
 -------------

django_typer/tests/test_app/management/commands/howto3.py

@@ -0,0 +1,19 @@
+from django_typer import TyperCommand, command
+from django_typer import initialize as root
+
+
+class Command(TyperCommand):
+
+    @root(invoke_without_command=True)
+    def handle(self, flag: bool = False):
+        # This is the root command, it runs when we run our command without
+        # any subcommand
+        print(flag)
+
+    @command()
+    def subcommand1(self):
+        pass
+
+    @command()
+    def subcommand2(self):
+        pass

doc/source/howto.rst

@@ -348,12 +348,27 @@ pass these options upstream to Typer_ by supplying them as keyword arguments to
     is undefined.
 
 
-Define Shell Completions for Parameter values
-----------------------------------------------
+Define Shell Tab Completions for Parameters
+-------------------------------------------
 
 See the section on :ref:`defining shell completions.<define-shellcompletions>`
 
 
+Debug Shell Tab Completers
+--------------------------
+
+See the section on :ref:`debugging shell completers.<debug-shellcompletions>`
+
+
+Extend/Override TyperCommands
+-----------------------------
+
+You can extend typer commands simply by subclassing them. All of the normal inheritance rules
+apply. You can either subclass an existing command from an upstream app and leave its module the
+same name to extend and override the command or you can subclass and rename the module to provide
+an adapted version of the upstream command with a different name.
+
+
 .. _configure-rich-exception-tracebacks:
 
 Configure rich_ Stack Traces

doc/source/index.rst

@@ -49,6 +49,10 @@ BaseCommand functionality is preserved, so that TyperCommand can be a drop in re
             'django_typer',
         ]
 
+   *You only need to install django_typer as an app if you want to use the shellcompletion command
+   to enable tab-completion or if you would like django-typer to install*
+   :ref:`rich traceback rendering <configure-rich-exception-tracebacks>` *for you - which it does by
+   default if rich is also installed.*
 
 :big:`Basic Example`
 

doc/source/shell_completion.rst

@@ -211,3 +211,23 @@ Django_ app labels like this:
 
     See the :class:`~django_typer.completers.ModelObjectCompleter` for a completer that works
     for many Django_ model field types.
+
+
+.. _debug-shellcompletions:
+
+Debugging Tab Completers
+========================
+
+Debugging tab completion code can be tricky because when invoked in situ in the shell the completer
+code is run as a subprocess and it's output is captured by the shell. This means you can't set a
+breakpoint and enter into the debugger easily.
+
+To help with this django-typer_ provides a debug mode that will enter into the tab-completion logic
+flow. Use the :class:`shellcompletion <django_typer.management.commands.shellcompletion.Command>`
+:func:`~django_typer.management.commands.shellcompletion.Command.complete` command, to pass the
+command line string that you would like to debug. For example:
+
+.. code-block:: bash
+
+    ./manage.py shellcompletion complete "mycommand --"
+