Work begins on #408 and #399

Author: kotfu

CONTRIBUTING.md

@@ -200,8 +200,29 @@ $ cd ~/src/cmd2
 $ pip install -e .[dev]
 ```
 
-This will install `pytest` and `tox` for running unit tests, `pylint` for
-static code analysis, and `sphinx` for building the documentation.
+This project uses many python modules for various development tasks, including
+testing, rendering documentation, and building and distributing releases. These
+modules can be configured many different ways, which can make it difficult to
+learn the specific incantations required for each project you are familiar with.
+
+This project uses `invoke <http://www.pyinvoke.org>`_ to provide a clean, high
+level interface for these development tasks. To see the full list of functions
+available::
+```bash
+$ invoke -l
+```
+
+You can run multiple tasks in a single invocation, for example::
+```bash
+$ invoke clean docs sdist wheel
+```
+
+That one command will remove all superflous cache, testing, and build
+files, render the documentation, and build a source distribution and a
+wheel distribution.
+
+If you want to see the details about what `invoke` is doing under the hood,
+have a look at `tasks.py`.
 
 Now you can check if everything is installed and working:
 ```bash
@@ -220,20 +241,32 @@ This bit is up to you!
 
 #### How to find the code in the cmd2 codebase to fix/edit?
 
-The cmd2 project directory structure is pretty simple and straightforward.  All actual code for cmd2
-is located underneath the `cmd2` directory.  The code to generate the documentation is in the `docs` directory.  Unit tests are in the `tests` directory.  The `examples` directory contains examples of how
-to use cmd2.  There are various other files in the root directory, but these are primarily related to
-continuous integration and to release deployment.
+The cmd2 project directory structure is pretty simple and straightforward.  All
+actual code for cmd2 is located underneath the `cmd2` directory.  The code to
+generate the documentation is in the `docs` directory.  Unit tests are in the
+`tests` directory.  The `examples` directory contains examples of how to use
+cmd2.  There are various other files in the root directory, but these are
+primarily related to continuous integration and to release deployment.
 
 #### Changes to the documentation files
-If you made changes to any file in the `/docs` directory, you need to build the Sphinx documentation
-and make sure your changes look good:
-```shell
-cd docs
-make clean html
+
+If you made changes to any file in the `/docs` directory, you need to build the
+Sphinx documentation and make sure your changes look good:
+```bash
+invoke docs
 ```
 In order to see the changes, use your web browser of choice to open `<cmd2>/docs/_build/html/index.html`.
 
+If you would rather use a webserver to view the documentation, including
+automatic page refreshes as you edit the files, use:
+
+```bash
+invoke livehtml
+```
+
+You will be shown the IP address and port number where the documents are now
+served. Put that into your web browser and edit away.
+
 ### Static Code Analysis
 
 You should have some sort of [PEP8](https://www.python.org/dev/peps/pep-0008/)-based linting running in your editor or IDE or at the command-line before you commit code.  [pylint](https://www.pylint.org) is a good Python linter which can be run at the command-line but also can integrate with many IDEs and editors.
@@ -244,7 +277,7 @@ You should have some sort of [PEP8](https://www.python.org/dev/peps/pep-0008/)-b
 When you're ready to share your code, run the test suite:
 ```shell
 cd <cmd2>
-py.test
+invoke pytest
 ```
 and ensure all tests pass.
 

setup.py

@@ -73,6 +73,7 @@
     # install with 'pip install -e .[dev]'
     'dev': [
         'pytest', 'pytest-cov', 'tox', 'pylint', 'sphinx', 'sphinx-rtd-theme',
+        'sphinx-autobuild','invoke',
     ]
 }
 

tasks.py

@@ -0,0 +1,184 @@
+#
+# coding=utf-8
+"""Development related tasks to be run with 'invoke'"""
+
+import os
+import shutil
+
+import invoke
+
+# shared function
+def rmrf(dirs, verbose=True):
+    "Silently remove a list of directories"
+    if isinstance(dirs, str):
+        dirs = [dirs]
+
+    for dir_ in dirs:
+        if verbose:
+            print("Removing {}".format(dir_))
+        shutil.rmtree(dir_, ignore_errors=True)
+
+
+# create namespaces
+namespace = invoke.Collection()
+namespace_clean = invoke.Collection('clean')
+namespace.add_collection(namespace_clean, 'clean')
+
+#####
+#
+# pytest, tox, pylint, and codecov
+#
+#####
+@invoke.task
+def pytest(context):
+    "Run tests and code coverage using pytest"
+    context.run("pytest --cov=cmd2 --cov-report=html")
+namespace.add_task(pytest)
+
+@invoke.task
+def pytest_clean(context):
+    "Remove pytest cache directories"
+    #pylint: disable=unused-argument
+    dirs = ['.pytest-cache', '.cache', 'htmlcov']
+    rmrf(dirs)
+namespace_clean.add_task(pytest_clean, 'pytest')
+
+@invoke.task
+def tox(context):
+    "Run unit and integration tests on multiple python versions using tox"
+    context.run("tox")
+namespace.add_task(tox)
+
+@invoke.task
+def tox_clean(context):
+    "Remove tox virtualenvs and logs"
+    #pylint: disable=unused-argument
+    rmrf('.tox')
+namespace_clean.add_task(tox_clean, 'tox')
+
+@invoke.task
+def codecov_clean(context):
+    "Remove code coverage reports"
+    #pylint: disable=unused-argument
+    dirs = set()
+    for name in os.listdir(os.curdir):
+        if name.startswith('.coverage'):
+            dirs.add(name)
+    rmrf(dirs)
+namespace_clean.add_task(codecov_clean, 'coverage')
+
+
+#####
+#
+# documentation
+#
+#####
+DOCS_SRCDIR = 'docs'
+DOCS_BUILDDIR = os.path.join('docs', '_build')
+
+@invoke.task()
+def docs(context, builder='html'):
+    "Build documentation using sphinx"
+    cmdline = 'python -msphinx -M {} {} {}'.format(builder, DOCS_SRCDIR, DOCS_BUILDDIR)
+    context.run(cmdline)
+namespace.add_task(docs)
+
+@invoke.task
+def docs_clean(context):
+    "Remove rendered documentation"
+    #pylint: disable=unused-argument
+    rmrf(DOCS_BUILDDIR)
+namespace_clean.add_task(docs_clean, name='docs')
+
+@invoke.task
+def livehtml(context):
+    "Launch webserver on http://localhost:8000 with rendered documentation"
+    builder = 'html'
+    outputdir = os.path.join(DOCS_BUILDDIR, builder)
+    cmdline = 'sphinx-autobuild -b {} {} {}'.format(builder, DOCS_SRCDIR, outputdir)
+    context.run(cmdline, pty=True)
+namespace.add_task(livehtml)
+
+
+#####
+#
+# build and distribute
+#
+#####
+BUILDDIR = 'build'
+DISTDIR = 'dist'
+
+@invoke.task
+def build_clean(context):
+    "Remove the build directory"
+    #pylint: disable=unused-argument
+    rmrf(BUILDDIR)
+namespace_clean.add_task(build_clean, 'build')
+
+@invoke.task
+def dist_clean(context):
+    "Remove the dist directory"
+    #pylint: disable=unused-argument
+    rmrf(DISTDIR)
+namespace_clean.add_task(dist_clean, 'dist')
+
+@invoke.task
+def eggs_clean(context):
+    "Remove egg directories"
+    #pylint: disable=unused-argument
+    dirs = set()
+    dirs.add('.eggs')
+    for name in os.listdir(os.curdir):
+        if name.endswith('.egg-info'):
+            dirs.add(name)
+        if name.endswith('.egg'):
+            dirs.add(name)
+    rmrf(dirs)
+namespace_clean.add_task(eggs_clean, 'eggs')
+
+@invoke.task
+def pycache_clean(context):
+    "Remove __pycache__ directories"
+    #pylint: disable=unused-argument
+    dirs = set()
+    for root, dirnames, _ in os.walk(os.curdir):
+        if '__pycache__' in dirnames:
+            dirs.add(os.path.join(root, '__pycache__'))
+    print("Removing __pycache__ directories")
+    rmrf(dirs, verbose=False)
+namespace_clean.add_task(pycache_clean, 'pycache')
+
+#
+# make a dummy clean task which runs all the tasks in the clean namespace
+clean_tasks = list(namespace_clean.tasks.values())
+@invoke.task(pre=list(namespace_clean.tasks.values()), default=True)
+def clean_all(context):
+    "Run all clean tasks"
+    #pylint: disable=unused-argument
+    pass
+namespace_clean.add_task(clean_all, 'all')
+
+@invoke.task
+def sdist(context):
+    "Create a source distribution"
+    context.run('python setup.py sdist')
+namespace.add_task(sdist)
+
+@invoke.task
+def wheel(context):
+    "Build a wheel distribution"
+    context.run('python setup.py bdist_wheel')
+namespace.add_task(wheel)
+
+@invoke.task(pre=[clean_all, sdist, wheel])
+def pypi(context):
+    "Build and upload a distribution to pypi"
+    context.run('twine upload dist/*')
+namespace.add_task(pypi)
+
+@invoke.task(pre=[clean_all, sdist, wheel])
+def pypi_test(context):
+    "Build and upload a distribution to https://test.pypi.org"
+    context.run('twine upload --repository-url https://test.pypi.org/legacy/ dist/*')
+namespace.add_task(pypi_test)
+