More `pecan.commands` documentation.

docs/source/commands.rst

@@ -95,3 +95,8 @@ which can be specified with the ``--shell`` flag (or its abbreviated alias,
 ::
     $ pecan shell --shell=ipython config.py
     $ pecan shell -s bpython config.py
+
+
+Extending ``pecan`` with Custom Commands
+----------------------------------------
+TODO

docs/source/index.rst

@@ -65,6 +65,7 @@ docstrings here:
    :maxdepth: 2
    
    pecan_core.rst
+   pecan_commands.rst
    pecan_configuration.rst
    pecan_decorators.rst
    pecan_deploy.rst

docs/source/pecan_commands.rst

@@ -0,0 +1,26 @@
+.. _pecan_commands:
+
+:mod:`pecan.commands` -- Pecan Commands
+=======================================
+
+The :mod:`pecan.commands` module implements the ``pecan`` console script
+used to provide (for example) ``pecan serve`` and ``pecan shell`` command line
+utilities.
+
+.. automodule:: pecan.commands.base
+  :members:
+  :show-inheritance:
+
+:mod:`pecan.commands.server` -- Pecan Development Server
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: pecan.commands.serve
+  :members:
+  :show-inheritance:
+
+:mod:`pecan.commands.shell` -- Pecan Interactive Shell
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: pecan.commands.shell
+  :members:
+  :show-inheritance:

pecan/commands/base.py

@@ -109,7 +109,33 @@ class CommandRunner(object):
 
 
 class BaseCommand(object):
-    """ Base class for Pecan commands. """
+    """
+    A base interface for Pecan commands.
+
+    Can be extended to support ``pecan`` command extensions in individual Pecan
+    projects, e.g.,
+
+    $ ``pecan my-custom-command config.py``
+
+    ::
+
+        # myapp/myapp/custom_command.py
+        class CustomCommand(pecan.commands.base.BaseCommand):
+            '''
+            (First) line of the docstring is used to summarize the command.
+            '''
+
+            arguments = ({
+                'command': '--extra_arg',
+                'help': 'an extra command line argument',
+                'optional': True
+            })
+
+            def run(self, args):
+                super(SomeCommand, self).run(args)
+                print args.extra_arg
+                print self.load_app()
+    """
 
     class __metaclass__(type):
         @property