Merge pull request #712 from python-cmd2/docstructure

New Documentation Structure

6 files changed, 73 insertions, 0 deletions

diff --git a/docs/migrating/free_features.rst b/docs/migrating/free_features.rst
new file mode 100644
index 00000000..afb29fc3
--- /dev/null
+++ b/docs/migrating/free_features.rst
@@ -0,0 +1,5 @@
+What you get for free
+=====================
+
+A brief list (with links to details) of major features you get for free once
+you migrate.
diff --git a/docs/migrating/incompatibilities.rst b/docs/migrating/incompatibilities.rst
new file mode 100644
index 00000000..7a8a5aba
--- /dev/null
+++ b/docs/migrating/incompatibilities.rst
@@ -0,0 +1,22 @@
+Incompatibilities
+=================
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
+``cmd2`` strives to be drop-in compatible with cmd_, however there are a few
+things that are not.
+
+
+cmd.emptyline()
+---------------
+
+The `cmd.emptyline()
+<https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline>`_ function is
+called when an empty line is entered in response to the prompt. By default, in
+cmd_ if this method is not overridden, it repeats and executes the last
+nonempty command entered.  However, no end user we have encountered views this
+as expected or desirable default behavior.  Thus, the default behavior in
+``cmd2`` is to simply go to the next line and issue the prompt again.  At this
+time, cmd2 completely ignores empty lines and the base class cmd.emptyline()
+method never gets called and thus the emptyline() behavior cannot be
+overridden.
diff --git a/docs/migrating/index.rst b/docs/migrating/index.rst
new file mode 100644
index 00000000..9c01b1bd
--- /dev/null
+++ b/docs/migrating/index.rst
@@ -0,0 +1,11 @@
+Migrating from cmd
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   why
+   incompatibilities
+   minimum
+   free_features
+   nextsteps
diff --git a/docs/migrating/minimum.rst b/docs/migrating/minimum.rst
new file mode 100644
index 00000000..d604cf7a
--- /dev/null
+++ b/docs/migrating/minimum.rst
@@ -0,0 +1,4 @@
+Minimum required changes
+========================
+
+The minimum required changes to move to cmd2
diff --git a/docs/migrating/nextsteps.rst b/docs/migrating/nextsteps.rst
new file mode 100644
index 00000000..3f560501
--- /dev/null
+++ b/docs/migrating/nextsteps.rst
@@ -0,0 +1,6 @@
+Next Steps
+==========
+
+What features (with links to details) are easy to implement next
+
+:doc:`Help <../features/help>`
diff --git a/docs/migrating/why.rst b/docs/migrating/why.rst
new file mode 100644
index 00000000..71017d89
--- /dev/null
+++ b/docs/migrating/why.rst
@@ -0,0 +1,25 @@
+Why Migrate to cmd2
+===================
+
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
+``cmd2`` is an extension of cmd_, the Python Standard Library's module for
+creating simple interactive command-line applications.
+
+``cmd2`` can be used as a drop-in replacement for cmd_.  Simply importing
+``cmd2`` in place of cmd_ will add many features to an application without any
+further modifications.
+
+Understanding the use of cmd_ is the first step in learning the use of
+``cmd2``. Once you have read the cmd_ docs, return here to learn the ways that
+``cmd2`` differs from cmd_.
+
+
+Describe why you would want to migrate, and the benefits of doing so
+
+Unicode
+
+features
+
+active community
+