diff options
| -rwxr-xr-x | README.rst | 44 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/install.rst | 84 |
3 files changed, 120 insertions, 9 deletions
@@ -1,6 +1,5 @@ -----
cmd2
-----
+====
.. image:: https://secure.travis-ci.org/python-cmd2/cmd2.png?branch=master
:target: https://travis-ci.org/python-cmd2/cmd2
@@ -21,11 +20,32 @@ cmd2 :target: https://pypi.python.org/pypi/cmd2/
:alt: License
-:Author: Catherine Devlin, http://catherinedevlin.blogspot.com
+cmd2 is a tool for writing command-line interactive applications for Python 2.7 and Python 3.3+. It is based on the
+ Python Standard Library's cmd_ module, and can be used anyplace cmd is used simply by importing cmd2 instead. It is
+ pure Python code with the only 3rd-party dependencies being on six_ and pyparsing_
-`cmd2` is a tool for writing command-line interactive applications. It is based on the Python Standard Library's `cmd` module, and can be used anyplace `cmd` is used simply by importing `cmd2` instead.
+.. _cmd: https://docs.python.org/3/library/cmd.html
+.. _six: https://pypi.python.org/pypi/six
+.. _pyparsing:: http://pyparsing.wikispaces.com
-`cmd2` provides the following features, in addition to those already existing in `cmd`:
+The latest documentation for cmd2 can be read online here: https://cmd2.readthedocs.io/en/latest/
+
+See the `Installation Instructions`_ in the cmd2 documentation for instructions on installing, upgrading, and
+uninstalling cmd2.
+
+.. _`Installation Instructions`: https://cmd2.readthedocs.io/en/latest/install.html
+
+The project is `maintained at GitHub`_. Bug reports may be submitted directly to the `issue tracker`_. Tested pull
+requests, especially ones with pytest_ unit tests are welcome.
+
+.. _`maintained at GitHub`: https://github.com/python-cmd2/cmd2
+.. _`issue tracker`: https://github.com/python-cmd2/cmd2/issues
+.. _pytest: http://docs.pytest.org
+
+
+Feature Support
+---------------
+cmd2 provides the following features, in addition to those already existing in `cmd`:
- Searchable command history
- Load commands from file, save to file, edit commands in file
@@ -83,14 +103,20 @@ Instructions for implementing each feature follow. See Python standard library's `optparse` documentation: http://docs.python.org/lib/optparse-defining-options.html
-cmd2 can be installed from a Linux distribution using their default package manager or `pip install cmd2`
-**Official documentation** for the `latest release <http://cmd2.readthedocs.io/en/stable/>`_, `development <http://cmd2.readthedocs.io/en/latest/>`_ and `0.6.9 <http://cmd2.readthedocs.io/en/0.6.9/>`_
+Tutorials
+---------
+A couple tutorials on using cmd2 exist:
+ * A detailed PyCon 2010 talk by `Catherine Devlin`_, the original author
+ * http://pyvideo.org/pycon-us-2010/pycon-2010--easy-command-line-applications-with-c.html
+ * A nice brief step-by-step tutorial
+ * https://kushaldas.in/posts/developing-command-line-interpreters-using-python-cmd2.html
-PyPI page: http://pypi.python.org/pypi/cmd2
+.. _Catherine Devlin: https://github.com/catherinedevlin
-A nice step-by-step tutorial: https://kushaldas.in/posts/developing-command-line-interpreters-using-python-cmd2.html
+Example Application
+-------------------
Example cmd2 application (example/example.py) ::
'''A sample application for cmd2.'''
diff --git a/docs/index.rst b/docs/index.rst index ce295be7..666f202e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,6 +59,7 @@ Contents: .. toctree:: :maxdepth: 2 + install overview freefeatures settingchanges diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 00000000..8a9d3791 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,84 @@ + +========================= +Installation Instructions +========================= + +This section covers the basics of how to install, upgrade, and uninstall ``cmd2``. + +Installing +---------- +First you need to make sure you have Python 2.7 or Python 3.3+, pip_, and setuptools_. Then you can just use pip to +install from PyPI_. + +.. _pip: https://pypi.python.org/pypi/pip +.. _setuptools: https://pypi.python.org/pypi/setuptools +.. _PyPI: https://pypi.python.org/pypi + +Requirements for Installing +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* If you have Python 2 >=2.7.9 or Python 3 >=3.4 installed from `python.org + <https://www.python.org>`_, you will already have pip_ and + setuptools_, but may need to upgrade to the latest versions: + + On Linux or OS X: + + :: + + pip install -U pip setuptools + + + On Windows: + + :: + + python -m pip install -U pip setuptools + + +Use pip for Installing +~~~~~~~~~~~~~~~~~~~~~~ + +pip_ is the recommended installer. Installing with pip is easy:: + + pip install cmd2 + +This should also install the required 3rd-party dependencies, if necessary. + + +Install from Debian or Ubuntu repos +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +We recommend installing from pip_, but if you wish to install from Debian or Ubuntu repos this can be done with +apt-get. + +For Python 2:: + + sudo apt-get install python-cmd2 + +For Python 3:: + + sudo apt-get install python3-cmd2 + +This will also install the required 3rd-party dependencies. + + +Deploy cmd2.py with your project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This is an option suitable for advanced Python users. The ``cmd2`` module is a single file, **cmd2.py**. You can +simply include this file within your project's hierarchy. If you want to modify ``cmd2``, this may be a reasonable +option. Though, we would encourage you to use stock ``cmd2`` and inheritance to achieve the same goal. + + +Upgrading cmd2 +-------------- + +Upgrade an already installed ``cmd2`` to the latest version from PyPI_:: + + pip install -U cmd2 + +This will upgrade to the newest stable version of ``cmd2`` and will also upgrade any dependencies if necessary. + + +Uninstalling cmd2 +----------------- +If you wish to permanently uninstall ``cmd2``, this can also easily be done with pip_:: + + pip uninstall cmd2 |