Skeleton doc structure complete for #709

15 files changed, 253 insertions, 3 deletions

diff --git a/docs/features/clipboard.rst b/docs/features/clipboard.rst
new file mode 100644
index 00000000..0c69a279
--- /dev/null
+++ b/docs/features/clipboard.rst
@@ -0,0 +1,3 @@
+Clipboard Integration
+=====================
+
diff --git a/docs/features/completion.rst b/docs/features/completion.rst
new file mode 100644
index 00000000..c89b24cc
--- /dev/null
+++ b/docs/features/completion.rst
@@ -0,0 +1,4 @@
+Completion
+==========
+
+How tab completion works and how to implement it in your own project
diff --git a/docs/features/disable_commands.rst b/docs/features/disable_commands.rst
new file mode 100644
index 00000000..b0f7f11b
--- /dev/null
+++ b/docs/features/disable_commands.rst
@@ -0,0 +1,4 @@
+Disabling Commands
+==================
+
+How to disable and re-enable commands, by individual command and by category
diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst
new file mode 100644
index 00000000..ace68877
--- /dev/null
+++ b/docs/features/embedded_python_shells.rst
@@ -0,0 +1,4 @@
+Embedded Python Shells
+======================
+
+Describe ``py`` and optional ``ipy`` commands
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index a4a928cf..1dab6f64 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -3,8 +3,10 @@ Generating Output
 
 how to generate output
 
-poutput
+- poutput
+- perror
+- paging
+- exceptions
+- color support
 
-perror
 
-paging
diff --git a/docs/features/help.rst b/docs/features/help.rst
index e5cc0451..37280bf0 100644
--- a/docs/features/help.rst
+++ b/docs/features/help.rst
@@ -6,3 +6,134 @@ use the categorize() function to create help categories
 Use ``help_method()`` to custom roll your own help messages.
 
 See :ref:`features/argument_processing:Help Messages`
+
+Grouping Commands
+-----------------
+
+By default, the ``help`` command displays::
+
+  Documented commands (type help <topic>):
+  ========================================
+  alias  help     ipy    py    run_pyscript  set    shortcuts
+  edit   history  macro  quit  run_script    shell
+
+If you have a large number of commands, you can optionally group your commands into categories.
+Here's the output from the example ``help_categories.py``::
+
+  Documented commands (type help <topic>):
+
+  Application Management
+  ======================
+  deploy  findleakers  redeploy  sessions  stop
+  expire  list         restart   start     undeploy
+
+  Command Management
+  ==================
+  disable_commands  enable_commands
+
+  Connecting
+  ==========
+  connect  which
+
+  Server Information
+  ==================
+  resources  serverinfo  sslconnectorciphers  status  thread_dump  vminfo
+
+  Other
+  =====
+  alias   edit  history  py    run_pyscript  set    shortcuts
+  config  help  macro    quit  run_script    shell  version
+
+There are 2 methods of specifying command categories, using the ``@with_category`` decorator or with the
+``categorize()`` function. Once a single command category is detected, the help output switches to a categorized
+mode of display. All commands with an explicit category defined default to the category `Other`.
+
+Using the ``@with_category`` decorator::
+
+  @with_category(CMD_CAT_CONNECTING)
+  def do_which(self, _):
+      """Which command"""
+      self.poutput('Which')
+
+Using the ``categorize()`` function:
+
+    You can call with a single function::
+
+        def do_connect(self, _):
+            """Connect command"""
+            self.poutput('Connect')
+
+        # Tag the above command functions under the category Connecting
+        categorize(do_connect, CMD_CAT_CONNECTING)
+
+    Or with an Iterable container of functions::
+
+        def do_undeploy(self, _):
+            """Undeploy command"""
+            self.poutput('Undeploy')
+
+        def do_stop(self, _):
+            """Stop command"""
+            self.poutput('Stop')
+
+        def do_findleakers(self, _):
+            """Find Leakers command"""
+            self.poutput('Find Leakers')
+
+        # Tag the above command functions under the category Application Management
+        categorize((do_undeploy,
+                    do_stop,
+                    do_findleakers), CMD_CAT_APP_MGMT)
+
+The ``help`` command also has a verbose option (``help -v`` or ``help --verbose``) that combines
+the help categories with per-command Help Messages::
+
+    Documented commands (type help <topic>):
+
+    Application Management
+    ================================================================================
+    deploy              Deploy command
+    expire              Expire command
+    findleakers         Find Leakers command
+    list                List command
+    redeploy            Redeploy command
+    restart             usage: restart [-h] {now,later,sometime,whenever}
+    sessions            Sessions command
+    start               Start command
+    stop                Stop command
+    undeploy            Undeploy command
+
+    Connecting
+    ================================================================================
+    connect             Connect command
+    which               Which command
+
+    Server Information
+    ================================================================================
+    resources              Resources command
+    serverinfo             Server Info command
+    sslconnectorciphers    SSL Connector Ciphers command is an example of a command that contains
+                           multiple lines of help information for the user. Each line of help in a
+                           contiguous set of lines will be printed and aligned in the verbose output
+                           provided with 'help --verbose'
+    status                 Status command
+    thread_dump            Thread Dump command
+    vminfo                 VM Info command
+
+    Other
+    ================================================================================
+    alias               Define or display aliases
+    config              Config command
+    edit                Edit a file in a text editor
+    help                List available commands with "help" or detailed help with "help cmd"
+    history             usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]
+    py                  Invoke python command, shell, or script
+    quit                Exits this application
+    run_pyscript        Runs a python script file inside the console
+    run_script          Runs commands in script file that is encoded as either ASCII or UTF-8 text
+    set                 usage: set [-h] [-a] [-l] [settable [settable ...]]
+    shell               Execute a command as if at the OS prompt
+    shortcuts           Lists shortcuts available
+    unalias             Unsets aliases
+    version             Version command
+
diff --git a/docs/features/history.rst b/docs/features/history.rst
new file mode 100644
index 00000000..cbd3f3e6
--- /dev/null
+++ b/docs/features/history.rst
@@ -0,0 +1,8 @@
+Command History
+===============
+
+- Describe how cmd2 tracks history
+- describe the uses of the built in history command
+- how persistent history works
+- differences in history and bash shell history (we only store valid commands in history)
+- reference the public code structures we use to store history
diff --git a/docs/features/multiline.rst b/docs/features/multiline.rst
new file mode 100644
index 00000000..85a92bb2
--- /dev/null
+++ b/docs/features/multiline.rst
@@ -0,0 +1,17 @@
+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).
+
+In multiline commands, output redirection characters
+like ``>`` and ``|`` are part of the command
+arguments unless they appear after the terminator.
diff --git a/docs/features/os.rst b/docs/features/os.rst
new file mode 100644
index 00000000..f771fee2
--- /dev/null
+++ b/docs/features/os.rst
@@ -0,0 +1,10 @@
+Integrating with the OS
+=======================
+
+- how to redirect output
+- executing OS commands from within ``cmd2``
+- editors
+- paging
+- exit codes
+- Automation and calling cmd2 from other CLI/CLU tools via commands at invocation and quit
+
diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst
new file mode 100644
index 00000000..253666e7
--- /dev/null
+++ b/docs/features/plugins.rst
@@ -0,0 +1,3 @@
+Plugins
+=======
+
diff --git a/docs/features/prompt.rst b/docs/features/prompt.rst
new file mode 100644
index 00000000..bda0ec4e
--- /dev/null
+++ b/docs/features/prompt.rst
@@ -0,0 +1,35 @@
+Prompt
+======
+
+``cmd2`` can issue a prompt before soliciting user input.
+
+Asynchronous Feedback
+---------------------
+``cmd2`` provides two 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.
+
+async_alert()
+    Used to display an important message to the user while they are at the prompt in between commands.
+    To the user it appears as if an alert message is printed above the prompt and their current input
+    text and cursor location is left alone.
+
+async_update_prompt()
+    Updates the prompt while the user is still typing at it. This is good for alerting the user to system
+    changes dynamically in between commands. For instance you could alter the color of the prompt to indicate
+    a system status or increase a counter to report an event.
+
+``cmd2`` also provides a function to change the title of the terminal window. This feature requires the
+application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and
+greater all support these.
+
+set_window_title()
+    Sets the terminal window title
+
+
+The easiest way to understand these functions is to see the AsyncPrinting_ example for a demonstration.
+
+.. _AsyncPrinting: https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py
+
+
diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst
new file mode 100644
index 00000000..c6869774
--- /dev/null
+++ b/docs/features/scripting.rst
@@ -0,0 +1,18 @@
+Scripting
+=========
+
+Document use cases and commands for ``run_script`` and ``run_pyscript``
+
+Comments
+--------
+
+Any command line input where the first non-whitespace character is a `#` will be treated as a comment.
+This means any `#` character appearing later in the command will be treated as a literal. The same
+applies to a `#` in the middle of a multiline command, even if it is the first character on a line.
+
+Comments can be useful in :ref:`scripts`, but would be pointless within an interactive session.
+
+::
+
+  (Cmd) # this is a comment
+  (Cmd) this # is not a comment
\ No newline at end of file
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
new file mode 100644
index 00000000..696b085f
--- /dev/null
+++ b/docs/features/settings.rst
@@ -0,0 +1,6 @@
+Settings
+========
+
+- current settings and what they do
+- how a developer can add their own
+- how to hide built in settings from a user
diff --git a/docs/features/shortcuts_aliases_macros.rst b/docs/features/shortcuts_aliases_macros.rst
new file mode 100644
index 00000000..39b2c9c2
--- /dev/null
+++ b/docs/features/shortcuts_aliases_macros.rst
@@ -0,0 +1,3 @@
+Shortcuts, Aliases, and Macros
+==============================
+
diff --git a/docs/features/startup_commands.rst b/docs/features/startup_commands.rst
new file mode 100644
index 00000000..1efcc014
--- /dev/null
+++ b/docs/features/startup_commands.rst
@@ -0,0 +1,2 @@
+Startup Commands
+================