Spring cleaning (#788)

closes #797
closes #798
closes #799
closes #800
closes #801
closes #754

Also (no extra issues for that):

    removed all experimental markers from docstrings (most of them have been there for a few years already). If they turn out wrong/bad, we just have to deprecate them and remove them in a major release
    hookimpl is instantiated twice - mark one of them as deprecated and get rid of it later
    moved hookimpl to __init__.py - having a hookimpl object in the hookspecs module is unnecessary and confusing. Access to hookimpl should happen as module attribute of tox (clearer where it comes from) - also kept a deprecated reference there for compatibilty.
    removed some redundant rst references in hookspecs. If they are initialized once in any namespace they are defined globally (I don't like it either but that is how it works in restructuredText and ignoring that and defining the same things several times is confusing)
    move _dummy object to only class where it is needed and name it like the constant that it is
    use six for py2/3 compatibility where noticed it and where it is cheap to do
    remove dead code
    move exception related code into its own module rather than having it hang around in a class looking like a module in __init__.py
    there is no need to have an intermediate run_main - that is used everywhere only under the name tox.cmdline rename function and use it directly, just like client code is using it
    add a fixture for working in a clean tmpdir

Author: obestwalter

.pre-commit-config.yaml

@@ -7,11 +7,6 @@ repos:
     -   id: check-yaml
     -   id: debug-statements
     -   id: flake8
--   repo: https://github.com/asottile/reorder_python_imports
-    sha: v0.3.5
-    hooks:
-    -   id: reorder-python-imports
-        language_version: python3.6
 -   repo: https://github.com/asottile/pyupgrade
     sha: v1.2.0
     hooks:

CHANGELOG.rst

@@ -18,7 +18,7 @@ on Github:
 - `2.8 series of releases <https://github.com/tox-dev/tox/projects/6>`_
 
 ..
-    Everything below here is generated by `towncrier <https://pypi.python.org/pypi/towncrier>`_.
+    Everything below here is generated by `towncrier <https://pypi.org/project/towncrier>`_.
     It is generated once as part of the release process rendering fragments from the `changelog`
     folder. If necessary, the generated text can be edited afterwards to e.g. merge rc changes
     into the final release notes.
@@ -781,7 +781,7 @@ Improved Documentation
   location ({envtmpdir}/pseudo-home).  If an index url was specified
   a .pydistutils.cfg file will be written with an index_url setting
   so that packages defining ``setup_requires`` dependencies will not
-  silently use your HOME-directory settings or https://pypi.python.org/pypi.
+  silently use your HOME-directory settings or PyPi.
 
 - fix `#1 <https://github.com/tox-dev/tox/issues/1>`_: empty setup files are properly detected, thanks Anthon van
   der Neuth

HOWTORELEASE.rst

@@ -38,7 +38,6 @@ If you want to use the scripts in `task/` you need a `.pypirc` with a correctly
 .. code-block:: ini
 
     [pypi]
-    ;repository=https://pypi.python.org/pypi
     ;repository=https://upload.pypi.io/legacy/
     username=<your username>
     password=<your password>

MANIFEST.in

@@ -6,3 +6,6 @@ include setup.py
 include tox.ini
 graft doc
 graft tests
+
+global-exclude __pycache__
+global-exclude *.py[cod]

changelog/754.misc.rst

@@ -0,0 +1 @@
+filter out unwanted files in package - by @obestwalter

changelog/797.doc.rst

@@ -0,0 +1 @@
+extend the plugin documentation and make lot of small fixes and improvements - by @obestwalter

changelog/798.feature.rst

@@ -0,0 +1 @@
+introduce a constants module to be used internally and as experimental API - by @obestwalter

changelog/799.doc.rst

@@ -0,0 +1 @@
+tidy up tests - remove unused fixtures, update old cinstructs, etc. - by @obestwalter

changelog/800.misc.rst

@@ -0,0 +1 @@
+make the already existing implicit API explicit - by @obestwalter

changelog/801.misc.rst

@@ -0,0 +1 @@
+improve tox quickstart and corresponding tests - @obestwalter

changelog/examples.rst

@@ -1,10 +1,18 @@
+.. examples for changelog entries adding to your Pull Requests
+
+file ``544.doc.rst``::
+
+    explain everything much better - by @passionate_technicalwriter
+
 file ``544.feature.rst``::
 
-    ``tox --version`` now shows information about all registered plugins - by @obestwalter.
+    ``tox --version`` now shows information about all registered plugins - by @obestwalter
 
 
 file ``571.bugfix.rst``::
 
     ``skip_install`` overrides ``usedevelop`` (``usedevelop`` is an option to choose the
     installation type if the package is installed and `skip_install` determines if it should be
-    installed at all) - by @ferdonline.
+    installed at all) - by @ferdonline
+
+.. see tox/pyproject.toml for all available categories

doc/example/basic.rst

@@ -88,7 +88,7 @@ configuration:
                           /bin/bash
 
 
-.. _virtualenv: https://pypi.python.org/pypi/virtualenv
+.. _virtualenv: https://pypi.org/project/virtualenv
 
 .. _multiindex:
 
@@ -175,8 +175,8 @@ like this:
 
 .. code-block:: shell
 
-    tox -i DEV=http://pypi.python.org/simple  # changes :DEV: package URLs
-    tox -i http://pypi.python.org/simple      # changes default
+    tox -i DEV=http://pypi.org/simple  # changes :DEV: package URLs
+    tox -i http://pypi.org/simple      # changes default
 
 further customizing installation
 ---------------------------------

doc/example/pytest.rst

@@ -5,8 +5,6 @@ It is easy to integrate `pytest`_ runs with tox.  If you encounter
 issues, please check if they are `listed as a known issue`_ and/or use
 the :doc:`support channels <../support>`.
 
-.. _`pytest`: https://docs.pytest.org/en/latest/
-
 Basic example
 --------------------------
 

doc/example/unittest.rst

@@ -4,11 +4,9 @@ unittest2, discover and tox
 Running unittests with 'discover'
 ------------------------------------------
 
-.. _Pygments: https://pypi.python.org/pypi/Pygments
-
 The discover_ project allows to discover and run unittests
 and we can easily integrate it in a ``tox`` run.  As an example,
-perform a checkout of Pygments_:
+perform a checkout of `Pygments <https://pypi.org/project/Pygments>`_:
 
 .. code-block:: shell
 
@@ -34,7 +32,6 @@ Running unittest2 and sphinx tests in one go
 -----------------------------------------------------
 
 .. _`Michael Foord`: http://www.voidspace.org.uk/
-.. _tox.ini: https://github.com/testing-cabal/mock/blob/master/tox.ini
 
 `Michael Foord`_ has contributed a ``tox.ini`` file that
 allows you to run all tests for his mock_ project,
@@ -45,7 +42,8 @@ its repository with:
 
     git clone https://github.com/testing-cabal/mock.git
 
-the checkout has a tox.ini_ that looks like this:
+The checkout has a `tox.ini file <https://github.com/testing-cabal/mock/blob/master/tox.ini>`_
+that looks like this:
 
 .. code-block:: ini
 

doc/index.rst

@@ -33,9 +33,12 @@ right next to your ``setup.py`` file::
     # content of: tox.ini , put in same dir as setup.py
     [tox]
     envlist = py27,py36
+
     [testenv]
-    deps=pytest       # install pytest in the venvs
-    commands=pytest  # or 'nosetests' or ...
+    deps = pytest       # install pytest in the virtualenv where commands will be executed
+    commands =
+        # whatever extra steps before testing might be necessary
+        pytest          # or any other test runner that you might use
 
 You can also try generating a ``tox.ini`` file automatically, by running
 ``tox-quickstart`` and then answering a few simple questions.
@@ -63,13 +66,12 @@ Current features
 
     - test-tool agnostic: runs pytest, nose or unittests in a uniform manner
 
-* :doc:`(new in 2.0) plugin system <plugins>` to modify tox execution with simple hooks.
+* :doc:`plugin system <plugins>` to modify tox execution with simple hooks.
 
 * uses pip_ and setuptools_ by default.  Support for configuring the installer command
   through :confval:`install_command=ARGV`.
 
-* **cross-Python compatible**: CPython-2.7, 3.4 and higher,
-  Jython and pypy_.
+* **cross-Python compatible**: CPython-2.7, 3.4 and higher, Jython and pypy_.
 
 * **cross-platform**: Windows and Unix style environments
 
@@ -92,10 +94,6 @@ Current features
 * supports :ref:`using different / multiple PyPI index servers  <multiindex>`
 
 
-.. _pypy: http://pypy.org
-
-.. _`tox.ini`: :doc:configfile
-
 .. toctree::
    :hidden:
 

doc/links.rst

@@ -1,20 +1,24 @@
-
+.. _`Cookiecutter`: https://cookiecutter.readthedocs.io
+.. _`pluggy`: https://pluggy.readthedocs.io
+.. _`cookiecutter-tox-plugin`: https://github.com/tox-dev/cookiecutter-tox-plugin
 .. _devpi: http://doc.devpi.net
 .. _Python: http://www.python.org
-.. _virtualenv: https://pypi.python.org/pypi/virtualenv
-.. _virtualenv3: https://pypi.python.org/pypi/virtualenv3
-.. _virtualenv5: https://pypi.python.org/pypi/virtualenv5
-.. _`py.test`: http://pytest.org
+.. _virtualenv: https://pypi.org/project/virtualenv
+.. _`pytest`: https://pytest.org
 .. _nosetests:
-.. _`nose`: https://pypi.python.org/pypi/nose
+.. _`nose`: https://pypi.org/project/nose
 .. _`Holger Krekel`: https://twitter.com/hpk42
-.. _`pytest-xdist`: https://pypi.python.org/pypi/pytest-xdist
+.. _`pytest-xdist`: https://pypi.org/project/pytest-xdist
 
 .. _`easy_install`: http://peak.telecommunity.com/DevCenter/EasyInstall
-.. _pip: https://pypi.python.org/pypi/pip
-.. _setuptools: https://pypi.python.org/pypi/setuptools
+.. _pip: https://pypi.org/project/pip
+.. _setuptools: https://pypi.org/project/setuptools
 .. _`jenkins`: https://jenkins.io/index.html
-.. _sphinx: https://pypi.python.org/pypi/Sphinx
-.. _discover: https://pypi.python.org/pypi/discover
-.. _unittest2: https://pypi.python.org/pypi/unittest2
-.. _mock: https://pypi.python.org/pypi/mock/
+.. _sphinx: https://pypi.org/project/Sphinx
+.. _discover: https://pypi.org/project/discover
+.. _unittest2: https://pypi.org/project/unittest2
+.. _mock: https://pypi.org/project/mock/
+.. _pypy: http://pypy.org
+
+.. _`Python Packaging Guide`: https://packaging.python.org/tutorials/distributing-packages/#packaging-your-project
+.. _`tox.ini`: :doc:configfile