diff options
| -rw-r--r-- | docs/overview/integrating.rst | 48 | ||||
| -rw-r--r-- | docs/overview/summary.rst | 4 |
2 files changed, 31 insertions, 21 deletions
diff --git a/docs/overview/integrating.rst b/docs/overview/integrating.rst index b3770559..46dee4b4 100644 --- a/docs/overview/integrating.rst +++ b/docs/overview/integrating.rst @@ -1,27 +1,37 @@ -Integrate cmd2 into your project --------------------------------- +Integrate cmd2 Into Your Project +================================ -[TODO - show how to use semantic versions to add the correct version string to setup.py ] +Once installed, you will want to ensure that your project's dependencies +include ``cmd2``. Make sure your ``setup.py`` includes the following:: -[TODO - this is probably outdated advice] + install_requires=[ + 'cmd2>=1,<2', + ] -``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*. +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 +<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``. -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: +macOS Considerations +-------------------- - * attrs - * colorama - * pyperclip - * wcwidth +TODO need a section about how to get the right readline installed on macos -On Windows, there is an additional dependency: - * pyreadline
\ No newline at end of file +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``:: + + install_requires=[ + 'cmd2>=1,<2', + ":sys_platform=='win32'": ['pyreadline'], + ] diff --git a/docs/overview/summary.rst b/docs/overview/summary.rst index d6d7abb6..17d4732d 100644 --- a/docs/overview/summary.rst +++ b/docs/overview/summary.rst @@ -8,8 +8,8 @@ application? 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 built command line applications. Start -here to find out if this library is a good fit for your needs. +``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/featuretour:Feature Highlights` - a quick tour of a few of the features in ``cmd2``, for both developers and users |