diff options
Diffstat (limited to 'docs/overview')
| -rw-r--r-- | docs/overview/alternatives.rst | 47 | ||||
| -rw-r--r-- | docs/overview/installation.rst | 7 | ||||
| -rw-r--r-- | docs/overview/integrating.rst | 13 | ||||
| -rw-r--r-- | docs/overview/summary.rst | 11 |
4 files changed, 40 insertions, 38 deletions
diff --git a/docs/overview/alternatives.rst b/docs/overview/alternatives.rst index e8e8e3b3..63977334 100644 --- a/docs/overview/alternatives.rst +++ b/docs/overview/alternatives.rst @@ -2,10 +2,11 @@ Alternatives ============ For programs that do not interact with the user in a continuous loop - programs -that simply accept a set of arguments from the command line, return results, and -do not keep the user within the program's environment - all you need are sys_\ -.argv (the command-line arguments) and argparse_ (for parsing UNIX-style options -and flags). Though some people may prefer docopt_ or click_ to argparse_. +that simply accept a set of arguments from the command line, return results, +and do not keep the user within the program's environment - all you need are +sys_\ .argv (the command-line arguments) and argparse_ (for parsing UNIX-style +options and flags). Though some people may prefer docopt_ or click_ to +argparse_. .. _sys: https://docs.python.org/3/library/sys.html .. _argparse: https://docs.python.org/3/library/argparse.html @@ -16,15 +17,16 @@ and flags). Though some people may prefer docopt_ or click_ to argparse_. The curses_ module produces applications that interact via a plaintext terminal window, but are not limited to simple text input and output; they can paint the screen with options that are selected from using the cursor keys. However, -programming a curses_-based application is not as straightforward as using cmd_. +programming a curses_-based application is not as straightforward as using +cmd_. .. _curses: https://docs.python.org/3/library/curses.html .. _cmd: https://docs.python.org/3/library/cmd.html -Several Python packages exist for building interactive command-line applications -approximately similar in concept to cmd_ applications. None of them share -``cmd2``'s close ties to cmd_, but they may be worth investigating nonetheless. -Two of the most mature and full featured are: +Several Python packages exist for building interactive command-line +applications approximately similar in concept to cmd_ applications. None of +them share ``cmd2``'s close ties to cmd_, but they may be worth investigating +nonetheless. Two of the most mature and full featured are: * `Python Prompt Toolkit`_ * Click_ @@ -32,24 +34,21 @@ Two of the most mature and full featured are: .. _`Python Prompt Toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit `Python Prompt Toolkit`_ is a library for building powerful interactive command -lines and terminal applications in Python. It provides a lot of advanced visual -features like syntax highlighting, bottom bars, and the ability to create -fullscreen apps. +lines and terminal applications in Python. It provides a lot of advanced +visual features like syntax highlighting, bottom bars, and the ability to +create fullscreen apps. Click_ is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It is more geared towards command line utilities instead of command line interpreters, but it can be used for either. -Getting a working command-interpreter application based on either `Python Prompt -Toolkit`_ or Click_ requires a good deal more effort and boilerplate code than -``cmd2``. ``cmd2`` focuses on providing an excellent out-of-the-box experience -with as many useful features as possible built in for free with as little work -required on the developer's part as possible. We believe that ``cmd2`` provides -developers the easiest way to write a command-line interpreter, while allowing a -good experience for end users. If you are seeking a visually richer end-user -experience and don't mind investing more development time, we would recommend -checking out `Python Prompt Toolkit`_. - -In the future, we may investigate options for incorporating the usage of `Python -Prompt Toolkit`_ and/or Click_ into ``cmd2`` applications. +Getting a working command-interpreter application based on either `Python +Prompt Toolkit`_ or Click_ requires a good deal more effort and boilerplate +code than ``cmd2``. ``cmd2`` focuses on providing an excellent out-of-the-box +experience with as many useful features as possible built in for free with as +little work required on the developer's part as possible. We believe that +``cmd2`` provides developers the easiest way to write a command-line +interpreter, while allowing a good experience for end users. If you are +seeking a visually richer end-user experience and don't mind investing more +development time, we would recommend checking out `Python Prompt Toolkit`_. diff --git a/docs/overview/installation.rst b/docs/overview/installation.rst index fc44e740..9f1209b6 100644 --- a/docs/overview/installation.rst +++ b/docs/overview/installation.rst @@ -104,7 +104,8 @@ 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. +This will upgrade to the newest stable version of ``cmd2`` and will also +upgrade any dependencies if necessary. Uninstalling cmd2 @@ -121,8 +122,8 @@ macOS comes with the `libedit <http://thrysoee.dk/editline/>`_ library which is similar, but not identical, to GNU Readline. Tab-completion for ``cmd2`` applications is only tested against GNU Readline. -There are several ways GNU Readline can be installed within a Python environment -on a Mac, detailed in the following subsections. +There are several ways GNU Readline can be installed within a Python +environment on a Mac, detailed in the following subsections. gnureadline Python module diff --git a/docs/overview/integrating.rst b/docs/overview/integrating.rst index 146e5e35..e28df1a7 100644 --- a/docs/overview/integrating.rst +++ b/docs/overview/integrating.rst @@ -9,13 +9,13 @@ include ``cmd2``. Make sure your ``setup.py`` includes the following:: ] The ``cmd2`` project uses `Semantic Versioning <https://semver.org>`_, which -means that any incompatible API changes will be release with a new major version -number. We recommend that you follow the advice given by the Python Packaging -User Guide related to `install_requires +means that any incompatible API changes will be release with a new major +version number. We recommend that you follow the advice given by the Python +Packaging User Guide related to `install_requires <https://packaging.python.org/discussions/install-requires-vs-requirements/>`_. By setting an upper bound on the allowed version, you can ensure that your -project does not inadvertently get installed with an incompatible future version -of ``cmd2``. +project does not inadvertently get installed with an incompatible future +version of ``cmd2``. Windows Considerations @@ -23,7 +23,8 @@ Windows Considerations If you would like to use :ref:`features/completion:Completion`, and you want your application to run on Windows, you will need to ensure you install the -``pyreadline`` package. Make sure to include the following in your ``setup.py``:: +``pyreadline`` package. Make sure to include the following in your +``setup.py``:: install_requires=[ 'cmd2>=1,<2', diff --git a/docs/overview/summary.rst b/docs/overview/summary.rst index b59c86c2..9285014c 100644 --- a/docs/overview/summary.rst +++ b/docs/overview/summary.rst @@ -5,17 +5,18 @@ Building a new `REPL <https://en.wikipedia.org/wiki/Read–eval–print_loop>`_ `Command Line Interface <https://en.wikipedia.org/wiki/Command-line_interface>`_ application? -Already built an application that uses cmd_ from the python standard library and -want to add more functionality with very little work? +Already built an application that uses cmd_ from the python standard library +and want to add more functionality with very little work? ``cmd2`` is a powerful python library for building command line applications. Start here to find out if this library is a good fit for your needs. * :ref:`overview/installation:Installation Instructions` - how to install ``cmd2`` and associated optional dependencies -* :ref:`examples/first_app:First Application` - a sample application showing 8 key features of ``cmd2`` -* :ref:`overview/integrating:Integrate cmd2 Into Your Project` - adding ``cmd2`` - to your project +* :ref:`examples/first_app:First Application` - a sample application showing 8 + key features of ``cmd2`` +* :ref:`overview/integrating:Integrate cmd2 Into Your Project` - adding + ``cmd2`` to your project * :ref:`overview/alternatives:Alternatives` - other python packages that might meet your needs * :ref:`overview/resources:Resources` - related links and other materials |