From 92ae130c38520b249eb7351cfb0da1ad67d3d3cf Mon Sep 17 00:00:00 2001 From: kotfu Date: Tue, 2 Jul 2019 19:02:36 -0600 Subject: Major overhaul of documentation structure for #709 --- docs/migrating/free_features.rst | 5 +++++ docs/migrating/incompatibilities.rst | 21 +++++++++++++++++++++ docs/migrating/minimum.rst | 4 ++++ docs/migrating/nextsteps.rst | 6 ++++++ docs/migrating/why.rst | 25 +++++++++++++++++++++++++ 5 files changed, 61 insertions(+) create mode 100644 docs/migrating/free_features.rst create mode 100644 docs/migrating/incompatibilities.rst create mode 100644 docs/migrating/minimum.rst create mode 100644 docs/migrating/nextsteps.rst create mode 100644 docs/migrating/why.rst (limited to 'docs/migrating') 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..3d7ddcfb --- /dev/null +++ b/docs/migrating/incompatibilities.rst @@ -0,0 +1,21 @@ +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() +`_ 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/minimum.rst b/docs/migrating/minimum.rst new file mode 100644 index 00000000..098ba79c --- /dev/null +++ b/docs/migrating/minimum.rst @@ -0,0 +1,4 @@ +Minimum required changes +======================== + +The minimum required changes to move to cmd2 \ No newline at end of file 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..d1121128 --- /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 + -- cgit v1.2.1