From 51ea4ba9fbcdfc785a5e9d6bafcac69334e535a8 Mon Sep 17 00:00:00 2001 From: kotfu Date: Wed, 3 Jul 2019 11:23:58 -0600 Subject: Revise menu structure - collapse menu structure in sidebar so not everything is always shown - updates to Getting Started section --- docs/overview/alternatives.rst | 64 +++++++++-------- docs/overview/featuretour.rst | 9 ++- docs/overview/index.rst | 15 ++++ docs/overview/installation.rst | 160 +++++++++++++++++++++-------------------- docs/overview/integrating.rst | 27 +++++++ docs/overview/summary.rst | 19 +++++ 6 files changed, 181 insertions(+), 113 deletions(-) create mode 100644 docs/overview/index.rst create mode 100644 docs/overview/integrating.rst create mode 100644 docs/overview/summary.rst (limited to 'docs/overview') diff --git a/docs/overview/alternatives.rst b/docs/overview/alternatives.rst index bf1545d6..e8e8e3b3 100644 --- a/docs/overview/alternatives.rst +++ b/docs/overview/alternatives.rst @@ -1,13 +1,11 @@ -============================ -Alternatives to cmd and cmd2 -============================ +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_. +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_. .. _sys: https://docs.python.org/3/library/sys.html .. _argparse: https://docs.python.org/3/library/argparse.html @@ -15,39 +13,43 @@ or click_ to argparse_. .. _click: http://click.pocoo.org -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_. +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_. .. _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: +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_ .. _`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. +`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. -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 +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`_. + +In the future, we may investigate options for incorporating the usage of `Python +Prompt Toolkit`_ and/or Click_ into ``cmd2`` applications. diff --git a/docs/overview/featuretour.rst b/docs/overview/featuretour.rst index 15754733..a0d33da4 100644 --- a/docs/overview/featuretour.rst +++ b/docs/overview/featuretour.rst @@ -1,6 +1,5 @@ -Features -======== - -Briefly describe the list of major features, linking to the more detailed description -of each features elsewhere in the documentation. +Feature Highlights +================== +[Briefly describe the list of major features, linking to the more detailed description +of each features elsewhere in the documentation.] diff --git a/docs/overview/index.rst b/docs/overview/index.rst new file mode 100644 index 00000000..54415a33 --- /dev/null +++ b/docs/overview/index.rst @@ -0,0 +1,15 @@ +Getting Started +=============== + +.. toctree:: + :maxdepth: 1 + :hidden: + + featuretour + installation + integrating + alternatives + resources + ../examples/quickstart + +.. include:: summary.rst diff --git a/docs/overview/installation.rst b/docs/overview/installation.rst index 62765704..fc44e740 100644 --- a/docs/overview/installation.rst +++ b/docs/overview/installation.rst @@ -2,110 +2,99 @@ 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 3.5+, 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 +``cmd2`` works on Linux, macOS, and Windows. It requires Python 3.5 or +higher, pip_, and setuptools_. If you've got all that, then you can just: + +.. code-block:: shell + + $ pip install cmd2 + .. note:: - Depending on how and where you have installed Python on your system and on what OS you are using, you may need to - have administrator or root privileges to install Python packages. If this is the case, take the necessary steps - required to run the commands in this section as root/admin, e.g.: on most Linux or Mac systems, you can precede them - with ``sudo``:: + Depending on how and where you have installed Python on your system and on + what OS you are using, you may need to have administrator or root privileges + to install Python packages. If this is the case, take the necessary steps + required to run the commands in this section as root/admin, e.g.: on most + Linux or Mac systems, you can precede them with ``sudo``: - sudo pip install + .. code-block:: shell + $ sudo pip install -Requirements for Installing -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* If you have Python 3 >=3.5 installed from `python.org - `_, you will already have pip_ and - setuptools_, but may need to upgrade to the latest versions: + +Prerequisites +------------- + +If you have Python 3 >=3.5 installed from `python.org +`_, you will already have pip_ and setuptools_, but may +need to upgrade to the latest versions: On Linux or OS X: - :: + .. code-block:: shell - pip install -U pip setuptools + $ pip install -U pip setuptools On Windows: - :: + .. code-block:: shell - python -m pip install -U pip setuptools + > python -m pip install -U pip setuptools .. _`pip_install`: -Use pip for Installing -~~~~~~~~~~~~~~~~~~~~~~ +Install from PyPI +----------------- + +pip_ is the recommended installer. Installing packages from PyPI_ with pip is +easy: -pip_ is the recommended installer. Installing packages from PyPI_ with pip is easy:: +.. code-block:: shell - pip install cmd2 + $ pip install cmd2 -This should also install the required 3rd-party dependencies, if necessary. +This will install the required 3rd-party dependencies, if necessary. .. _github: -Install from GitHub using pip -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Install from GitHub +------------------- -The latest version of ``cmd2`` can be installed directly from the master branch on GitHub using pip_:: +The latest version of ``cmd2`` can be installed directly from the master branch +on GitHub using pip_: - pip install -U git+git://github.com/python-cmd2/cmd2.git +.. code-block:: shell -This should also install the required 3rd-party dependencies, if necessary. + $ pip install -U git+git://github.com/python-cmd2/cmd2.git 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. +----------------------------------- + +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 3:: - sudo apt-get install python3-cmd2 + $ sudo apt-get install python3-cmd2 This will also install the required 3rd-party dependencies. .. warning:: - Versions of ``cmd2`` before 0.7.0 should be considered to be of unstable "beta" quality and should not be relied upon - for production use. If you cannot get a version >= 0.7 from your OS repository, then we recommend - installing from either pip or GitHub - see :ref:`pip_install` or :ref:`github`. - - -Deploy cmd2.py with your project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``cmd2`` is contained in a small number of Python files, which can be easily copied into your project. *The -copyright and license notice must be retained*. - -This is an option suitable for advanced Python users. You can simply include the files within your project's hierarchy. -If you want to modify ``cmd2``, this may be a reasonable option. Though, we encourage you to use stock ``cmd2`` and -either composition or inheritance to achieve the same goal. - -This approach will obviously NOT automatically install the required 3rd-party dependencies, so you need to make sure -the following Python packages are installed: - - * attrs - * colorama - * pyperclip - * wcwidth - -On Windows, there is an additional dependency: - - * pyreadline + Versions of ``cmd2`` before 0.7.0 should be considered to be of unstable + "beta" quality and should not be relied upon for production use. If you + cannot get a version >= 0.7 from your OS repository, then we recommend + installing from either pip or GitHub - see :ref:`pip_install` or + :ref:`github`. Upgrading cmd2 @@ -122,34 +111,51 @@ Uninstalling cmd2 ----------------- If you wish to permanently uninstall ``cmd2``, this can also easily be done with pip_:: - pip uninstall cmd2 + $ pip uninstall cmd2 + +macOS Considerations +-------------------- -Extra requirement for macOS -=========================== -macOS comes with the `libedit `_ library which is similar, but not identical, to GNU Readline. -Tab-completion for ``cmd2`` applications is only tested against GNU Readline. +macOS comes with the `libedit `_ 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 -------------------------- -Install the `gnureadline `_ Python module which is statically linked against a specific compatible version of GNU Readline:: +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install the `gnureadline `_ Python module which is statically linked against a specific compatible version of GNU Readline: + +.. code-block:: shell + + $ pip install -U gnureadline - pip install -U gnureadline readline via conda ------------------- -Install the **readline** package using the ``conda`` package manager included with the Anaconda Python distribution:: +~~~~~~~~~~~~~~~~~~ + +Install the **readline** package using the ``conda`` package manager included +with the Anaconda Python distribution: + +.. code-block:: shell + + $ conda install readline - conda install readline readline via brew ------------------ -Install the **readline** package using the Homebrew package manager (compiles from source):: +~~~~~~~~~~~~~~~~~ + +Install the **readline** package using the Homebrew package manager (compiles +from source): + +.. code-block:: shell - brew install openssl - brew install pyenv - brew install readline + $ brew install openssl + $ brew install pyenv + $ brew install readline Then use pyenv to compile Python and link against the installed readline diff --git a/docs/overview/integrating.rst b/docs/overview/integrating.rst new file mode 100644 index 00000000..b3770559 --- /dev/null +++ b/docs/overview/integrating.rst @@ -0,0 +1,27 @@ +Integrate cmd2 into your project +-------------------------------- + +[TODO - show how to use semantic versions to add the correct version string to setup.py ] + +[TODO - this is probably outdated advice] + +``cmd2`` is contained in a small number of Python files, which can be easily +copied into your project. *The copyright and license notice must be retained*. + +This is an option suitable for advanced Python users. You can simply include +the files within your project's hierarchy. If you want to modify ``cmd2``, this +may be a reasonable option. Though, we encourage you to use stock ``cmd2`` and +either composition or inheritance to achieve the same goal. + +This approach will obviously NOT automatically install the required 3rd-party +dependencies, so you need to make sure the following Python packages are +installed: + + * attrs + * colorama + * pyperclip + * wcwidth + +On Windows, there is an additional dependency: + + * pyreadline \ No newline at end of file diff --git a/docs/overview/summary.rst b/docs/overview/summary.rst new file mode 100644 index 00000000..4145d124 --- /dev/null +++ b/docs/overview/summary.rst @@ -0,0 +1,19 @@ + +.. _cmd: https://docs.python.org/3/library/cmd.html + +Building a new `REPL `_ or +`Command Line Interface `_ +application? ``cmd2`` is a powerful python library to help you get the job done. +Already built an application that uses cmd_ from the python standard library and +want to add more functionality with very little work? Begin here to find out if +``cmd2`` is a good fit for your needs. + +* :ref:`overview/featuretour:Feature Highlights` - a quick tour of a few of the + features in ``cmd2``, for both developers and users +* :ref:`overview/installation:Installation Instructions` - how to install + ``cmd2`` and associated optional dependencies +* :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 -- cgit v1.2.1