Add documentation

README.rst

@@ -1,4 +1,186 @@
+===============
 tox-current-env
 ===============
+---------------------------------------------------------------------------------------
+`tox <https://tox.readthedocs.io/>`_  plugin to run tests in current Python environment
+---------------------------------------------------------------------------------------
 
-... TODO ...
+The ``tox-current-env`` plugin adds two options:
+
+``tox --current-env``
+   Runs the tox testenv's ``commands`` in the current Python environment
+   (that is, the environment where ``tox`` is invoked from and installed in).
+   Unlike regular ``tox`` invocation, this installs no dependendencies declared in ``deps``.
+   An attempt to run this with a Python version that doesn't match will fail
+   (if ``tox`` is invoked from an Python 3.7 environment, any non 3.7 testenv will fail).
+
+``tox --print-deps-only``
+    Instead of running any ``commands``,
+    simply prints the declared dependencies in ``deps`` to the standard output.
+    This is useful for preparing the current environment for the above.
+
+Invoking ``tox`` without any of the above options should behave as regular ``tox`` invocation without this plugin.
+Any deviation from this behavior is considered a bug.
+
+
+Motivation
+----------
+
+Obviously, ``tox`` was created to run tests in isolated Python virtual environments.
+The ``--current-env`` flag totally defeats the purpose of ``tox``.
+Why would anybody do that, you might ask.
+
+This plugin was created for `Fedora <https://fedoralovespython.org/>`_'s needs.
+When we package Python software as RPM packages, we try to run the upstream test suite during package build.
+However there is no standardization of declaring Python test dependencies or invoking tests.
+The de-facto standard is ``tox``.
+However we need to test if the software works integrated into Fedora,
+not if it works with ``pip``-installed packages in an isolated environment.
+By running the tests in *current environment*, we can achieve that.
+
+If you are interested in the RPM packaging part of this,
+see Fedora's `%pyproject RPM macros <https://src.fedoraproject.org/rpms/pyproject-rpm-macros>`_.
+
+
+Installation
+------------
+
+Install this via ``pip``:
+
+.. code-block:: console
+
+   $ python -m pip install tox-current-env
+
+Or install the development version by cloning `the git repository <https://github.com/fedora-python/tox-current-env>`_
+and ``pip``-installing locally:
+
+.. code-block:: console
+
+   $ git clone https://github.com/fedora-python/tox-current-env
+   $ cd tox-current-env
+   $ python -m pip install -e .
+
+
+Usage
+-----
+
+When the plugin is installed, use ``tox`` with the ``--current-env`` or `` --print-deps-only`` and all the other options as usual. Assuming your ``tox`` is installed on Python 3.7:
+
+.. code-block:: console
+
+   $ tox -e py37 --current-env
+   py37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
+   py37 installed: ...list of packages from the current environment...
+   py37 run-test-pre: PYTHONHASHSEED='3333333333'
+   py37 run-test: commands...
+   ...runs tests in current environment's Python...
+   ___________________________________ summary ____________________________________
+     py37: commands succeeded
+     congratulations :)
+
+Attempting to run the ``py36`` environment's test will fail:
+
+.. code-block:: console
+
+   $ tox -e py37 --current-env
+   py36 create: /home/pythonista/projects/holy-grail/tests/.tox/py36
+   ERROR: InterpreterMismatch: tox_current_env: interpreter versions do not match:
+       in current env: (3, 7, 4, 'final', 0)
+       requested: (3, 6, 9, 'final', 0)
+   ___________________________________ summary ____________________________________
+   ERROR:  py36: InterpreterMismatch: tox_current_env: interpreter versions do not match:
+       in current env: (3, 7, 4, 'final', 0)
+       requested: (3, 6, 9, 'final', 0)
+
+To get list of test dependencies, run:
+
+.. code-block:: console
+
+   $ tox -e py37 --print-deps-only
+   py37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
+   py37 installed: ...you can see almost anything here...
+   py37 run-test-pre: PYTHONHASHSEED='3333333333'
+   dep1
+   dep2
+   ...
+   ___________________________________ summary ____________________________________
+     py37: commands succeeded
+     congratulations :)
+
+
+Caveats, warnings and limitations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Running (especially third party software's) tests in your system installed Python environment is dangerous.
+Always install ``tox`` and this plugin to some isolated environment,
+such as Python virtualenv, Linux container or chroot.
+You have been warned.
+
+In order to support the ``python`` command in the ``commands`` section,
+the current environment invocation of ``tox`` creates a fake virtual environment
+that just have a symbolic link to the Python executable.
+This can lead to slightly different results of tests than invoking them directly,
+especially if you have assumptions about ``sys.executable`` in your tests.
+Any other commands (such as ``pytest``) are not linked anywhere
+and it is the users' responsibility to make sure such commands are in ``$PATH`` and use the correct Python.
+
+Regardless of any `Python flags <https://docs.python.org/3/using/cmdline.html>`_ used in the shebang of ``tox``,
+the tests are invoked with ``sys.executable`` without any added flags
+(unless explicitly invoked with them in the ``commands`` section).
+
+The ``installed:`` line in the output of ``tox --print-deps-only`` shows irrelevant output
+(based on the content of the real or faked virtual environment).
+
+Running ``tox --current-env`` after regular ``tox``
+(that is without the ``--current-env`` switch)
+or vice versa is not supported without the ``--recreate/-r`` flag
+(``tox`` will emergency abort in that situation).
+Additionally, running ``tox --current-env``,
+uninstalling the ``tox-current-env``
+and running ``tox`` without the ``--recreate/-r`` flag
+will most likely attempt to install packages into your current environment
+and will provide further undefined results.
+Being uninstalled, ``tox-current-env`` cannot longer prevent this.
+
+The current environment's Python is tested for the major and minor version only.
+Possibly multiple different 3.X versions (such as CPython and PyPy) are treated as equal.
+
+Only Linux is supported, with special emphasis on Fedora.
+This plugin might work on other Unix-like systems,
+but does not work on Microsoft Windows.
+
+This is an alpha quality software.
+Use it at your on your own risk.
+
+
+Development, issues, support
+----------------------------
+
+The development happens on GitHub,
+at the `fedora-python/tox-current-env <https://github.com/fedora-python/tox-current-env>`_ repository.
+You can use the `issue tracker <https://github.com/fedora-python/tox-current-env/issues>`_  there for any discussion
+or send Pull Requests.
+
+
+Tests
+~~~~~
+
+In order to run the tests, you'll need ``tox`` and Python 3.6, 3.7 and 3.8 installed.
+The integration tests assume all three are available.
+On Fedora, you just need to ``dnf install tox``.
+
+Run ``tox`` to invoke the tests.
+
+Running tests of this plugin with this plugin installed and ``--current-env`` flag will most likely blow up.
+
+
+License
+-------
+
+The ``tox-current-env`` project is licensed under so-called MIT license, full text available in the `LICENSE <https://github.com/fedora-python/tox-current-env/blob/master/LICENSE>`_ file.
+
+
+Code of Conduct
+---------------
+
+The ``tox-current-env`` project follows the `Fedora's Code of Conduct <https://docs.fedoraproject.org/en-US/project/code-of-conduct/>`_.

setup.py

@@ -25,6 +25,7 @@ setup(
         "Framework :: tox",
         "Intended Audience :: Developers",
         "License :: OSI Approved :: MIT License",
+        "Operating System :: POSIX :: Linux",
         "Programming Language :: Python :: 3 :: Only",
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",