Merge pull request #422 from python-cmd2/invoke

Move from fab to invoke

Author: tleonhardt

CONTRIBUTING.md

@@ -67,9 +67,9 @@ The tables below list all prerequisites along with the minimum required version
 
 If Python is already installed in your machine, run the following commands to validate the versions:
 
-```shell
-python -V
-pip freeze | grep pyperclip
+```sh
+$ python -V
+$ pip freeze | grep pyperclip
 ```
 
 If your versions are lower than the prerequisite versions, you should update.
@@ -95,7 +95,7 @@ If you do not already have Python installed on your machine, we recommend using
 1. Open a Terminal / Command Line / Bash Shell in your projects directory (_i.e.: `/yourprojectdirectory/`_)
 2. Clone your fork of cmd2
 
-```shell
+```sh
 $ git clone https://github.com/yourUsername/cmd2.git
 ```
 
@@ -108,7 +108,7 @@ This will download the entire cmd2 repo to your projects directory.
 1. Change directory to the new cmd2 directory (`cd cmd2`)
 2. Add a remote to the official cmd2 repo:
 
-```shell
+```sh
 $ git remote add upstream https://github.com/python-cmd2/cmd2.git
 ```
 
@@ -124,29 +124,29 @@ Do this prior to every time you create a branch for a PR:
 
 1. Make sure you are on the `master` branch
 
-  > ```shell
+  > ```sh
   > $ git status
   > On branch master
   > Your branch is up-to-date with 'origin/master'.
   > ```
 
   > If your aren't on `master`, resolve outstanding files / commits and checkout the `master` branch
 
-  > ```shell
+  > ```sh
   > $ git checkout master
   > ```
 
 2. Do A Pull with Rebase Against `upstream`
 
-  > ```shell
+  > ```sh
   > $ git pull --rebase upstream master
   > ```
 
   > This will pull down all of the changes to the official master branch, without making an additional commit in your local repo.
 
 3. (_Optional_) Force push your updated master branch to your GitHub fork
 
-  > ```shell
+  > ```sh
   > $ git push origin master --force
   > ```
 
@@ -164,13 +164,13 @@ Name the branch something like `fix/xxx` or `feature/xxx` where `xxx` is a short
 
 To create a branch on your local machine (and switch to this branch):
 
-```shell
+```sh
 $ git checkout -b [name_of_your_new_branch]
 ```
 
 and to push to GitHub:
 
-```shell
+```sh
 $ git push origin [name_of_your_new_branch]
 ```
 
@@ -180,12 +180,12 @@ $ git push origin [name_of_your_new_branch]
 ### Setup for cmd2 development
 For doing cmd2 development, you actually do NOT want to have cmd2 installed as a Python package.
 So if you have previously installed cmd2, make sure to uninstall it:
-```bash
-pip uninstall cmd2
+```sh
+$ pip uninstall cmd2
 ```
 
 Assuming you cloned the repository to `~/src/cmd2`:
-```bash
+```sh
 $ cd ~/src/cmd2
 $ pip install -e .
 ```
@@ -195,18 +195,39 @@ imports `cmd2`, there is no need to re-install the module after every change. Th
 command will also install all of the runtime dependencies for `cmd2`.
 
 Next you should install all the modules used for development of `cmd2`:
-```bash
+```sh
 $ 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::
+```sh
+$ invoke -l
+```
+
+You can run multiple tasks in a single invocation, for example::
+```sh
+$ invoke 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
-cd ~src/cmd2
-python examples/example.py
+```sh
+$ cd ~src/cmd2
+$ python examples/example.py
 ```
 
 If the example app loads, you should see a prompt that says "(Cmd)".  You can
@@ -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:
+```sh
+$ 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:
+
+```sh
+$ invoke livehtml
+```
+
+You will be shown the IP address and port number where the documents are now
+served (usually [http://localhost:8000](http://localhost:8000).
+
 ### 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.
@@ -242,21 +275,14 @@ You should have some sort of [PEP8](https://www.python.org/dev/peps/pep-0008/)-b
 
 ### Run The Test Suite
 When you're ready to share your code, run the test suite:
-```shell
-cd <cmd2>
-py.test
+```sh
+$ cd <cmd2>
+$ invoke pytest
 ```
 and ensure all tests pass.
 
-#### Measuring code coverage
-
-Code coverage can be measured as follows:
-
-```shell
-py.test --cov=cmd2 --cov-report=term-missing --cov-report=html
-```
-
-Then use your web browser of choice to look at the results which are in `<cmd2>/htmlcov/index.html`.
+Running the test suite also calculates test code coverage. A summary of coverage
+is shown on the screen. A full report is available in `<cmd2>/htmlcov/index.html`.
 
 ### Squash Your Commits
 When you make a pull request, it is preferable for all of your changes to be in one commit.
@@ -301,7 +327,7 @@ Instance of cmd2](#maintaining-your-fork).
 1.  Perform the maintenance step of rebasing `master`.
 2.  Ensure you are on the `master` branch using `git status`:
 
-```bash
+```sh
 $ git status
 On branch master
 Your branch is up-to-date with 'origin/master'.
@@ -458,6 +484,19 @@ excellent support for debugging console applications.
 
 [PyCharm](https://www.jetbrains.com/pycharm/) is also quite good and has very nice [Code Inspection](https://www.jetbrains.com/help/pycharm/code-inspection.html) capabilities.
 
-### Acknowledgement
+## Publishing a new release
+
+Since 0.9.2, the process of publishing a new release of `cmd2` to [PyPi](https://pypi.org/) has been
+mostly automated. The manual steps are all git operations. Here's the checklist:
+
+1. Make sure you are on the proper branch
+2. Make sure the version strings in `cmd2.py`, `conf.py`, `setup.py`, and `test_cmd2.py` are correct.
+3. Make sure all the unit tests pass.
+4. Make sure `CHANGELOG.md` describes the version and has the correct release date.
+5. Create and push a git tag that matches the version strings above.
+6. (Optional) Run `invoke pypi_test` to clean, build, and upload a new release to [Test PyPi](https://test.pypi.org)
+7. Run `invoke pypi` to clean, build, and upload a new release to [PyPi](https://pypi.org/)
+
+## Acknowledgement
 Thanks to the good folks at [freeCodeCamp](https://github.com/freeCodeCamp/freeCodeCamp) for creating
 an excellent `CONTRIBUTING` file which we have borrowed heavily from.

fabfile.py

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