Remove testr entry point

A "testr" entry-point was added to PBR in
I2227adf3643ffe6bcece0c7d2127d23e20d52f7a in Jun 2013.  However,
testrepository had already started providing this same
disutils.commands entry-point in Jan 2013 [1].

I am not sure if it is deterministic who wins when two packages
declare the same entry-point, but at least for me, running "python
setup.py testr ..." was not calling into any of the pbr hooks.  I
discovered this because I wanted to use the --coverage-package-name
argument provided by the pbr testr wrapper because to s/-/_ in dib.

The original change (I8e4bc9bb78be37b4d13f8d6c2edfe2d67554ad78)
overrides the setuptools provided "test" [2] to call testrepository
when it sees a .testr.conf file (falling back to nose for
compatability).  So it seems the intention was not to add a "testr"
command, but that "test" is overridden to run testr automatically when
available.

Therefore I think that testrepository owns the distutils.command
entry-point for "testr".  To avoid confusion we should remove the
duplicate entry-point here and just leave the "test" command
overrides.

I've added documentation on the test command.  The testr/test split is
quite confusing, being only one letter different, so that is called
out explicitly.  Comments in testr_command are updated to reflect
what's happening better.  This also converts the calls in tox.ini to
use the PBR wrapper "test".

[1] 2a36806c69 (diff-2eeaed663bd0d25b7e608891384b7298R96)
[2] https://github.com/pypa/setuptools/blob/master/setuptools/command/test.py

Change-Id: I5b68f03e782fef5c45424c04cc851be5988f9019

doc/source/index.rst

@@ -390,6 +390,53 @@ environment, you can use::
     testing =
         quux:python_version=='2.7'
 
+
+Testing
+-------
+
+pbr overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py
+test``).  The following sequence is followed:
+
+#. If a ``.testr.conf`` file exists and `testrepository
+   <https://pypi.python.org/pypi/testrepository>`__ is installed, PBR
+   will use it as the test runner.  See the ``testr`` documentation
+   for more details.
+
+   .. note::
+
+     This is separate to ``setup.py testr`` (note the extra ``r``) which
+     is provided directly by the ``testrepository`` package.  Be careful
+     as there is some overlap of command arguments.
+
+#. Although deprecated, if ``[nosetests]`` is defined in ``setup.cfg``
+   and `nose <http://nose.readthedocs.io/en/latest/>`__ is installed,
+   the ``nose`` runner will be used.
+
+#. In other cases no override will be installed and the ``test``
+   command will revert to `setuptools
+   <http://setuptools.readthedocs.io/en/latest/setuptools.html#test-build-package-and-run-a-unittest-suite>`__.
+
+A typical usage would be in ``tox.ini`` such as::
+
+  [tox]
+  minversion = 2.0
+  skipsdist = True
+  envlist = py33,py34,py35,py26,py27,pypy,pep8,docs
+
+  [testenv]
+  usedevelop = True
+  setenv =
+    VIRTUAL_ENV={envdir}
+    CLIENT_NAME=pbr
+  deps = .
+       -r{toxinidir}/test-requirements.txt
+  commands =
+    python setup.py test --testr-args='{posargs}'
+
+The argument ``--coverage`` will set ``PYTHON`` to ``coverage run`` to
+produce a coverage report.  ``--coverage-package-name`` can be used to
+modify or narrow the packages traced.
+
 Additional Docs
 ===============
 

pbr/testr_command.py

@@ -26,16 +26,18 @@
 # license you chose for the specific language governing permissions and
 # limitations under that license.
 
-"""setuptools/distutils commands to run testr via setup.py
+"""setuptools/distutils command to run testr via setup.py
 
-Currently provides 'testr' which runs tests using testr. You can pass
---coverage which will also export PYTHON='coverage run --source <your package>'
-and automatically combine the coverage from each testr backend test runner
-after the run completes.
+PBR will hook in the Testr class to provide "setup.py test" when
+.testr.conf is present in the repository (see pbr/hooks/commands.py).
+
+If we are activated but testrepository is not installed, we provide a
+sensible error.
+
+You can pass --coverage which will also export PYTHON='coverage run
+--source <your package>' and automatically combine the coverage from
+each testr backend test runner after the run completes.
 
-To use, just use setuptools/distribute and depend on testr, and it should be
-picked up automatically (as the commands are exported in the testrepository
-package metadata.
 """
 
 from distutils import cmd

setup.cfg

@@ -42,8 +42,6 @@ autodoc_tree_excludes =
 [entry_points]
 distutils.setup_keywords =
     pbr = pbr.core:pbr
-distutils.commands =
-    testr = pbr.testr_command:Testr
 egg_info.writers =
     pbr.json = pbr.pbr_json:write_pbr_json
 console_scripts =

tox.ini

@@ -13,7 +13,7 @@ setenv =
 deps = .
        -r{toxinidir}/test-requirements.txt
 commands =
-  python setup.py testr --testr-args='{posargs}'
+  python setup.py test --testr-args='{posargs}'
 
 [tox:jenkins]
 sitepackages = True
@@ -26,7 +26,7 @@ commands = python setup.py build_sphinx
 
 [testenv:cover]
 commands =
-  python setup.py testr --coverage
+  python setup.py test --coverage
 
 [testenv:venv]
 commands = {posargs}