From c64ba412ebc2ee09df5fb49590a3cf1eadaffad8 Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 14:30:41 +0100 Subject: [PATCH 1/9] restart with a fresh addressing suggestions from previous PR --- README.rst | 151 ++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 120 insertions(+), 31 deletions(-) diff --git a/README.rst b/README.rst index 28b1b1f7c..45666b4fe 100644 --- a/README.rst +++ b/README.rst @@ -1,44 +1,133 @@ -.. image:: https://badge.fury.io/py/tox.svg - :target: https://badge.fury.io/py/tox - :alt: Latest version on PyPI -.. image:: https://img.shields.io/pypi/pyversions/tox.svg - :target: https://pypi.org/project/tox/ - :alt: Supported Python versions -.. image:: https://dev.azure.com/toxdev/tox/_apis/build/status/tox%20ci?branchName=master - :target: https://dev.azure.com/toxdev/tox/_build/latest?definitionId=9&branchName=master - :alt: Azure Pipelines build status -.. image:: https://api.codeclimate.com/v1/badges/425c19ab2169a35e1c16/test_coverage - :target: https://codeclimate.com/github/tox-dev/tox/code?sort=test_coverage - :alt: Test Coverage -.. image:: https://readthedocs.org/projects/tox/badge/?version=latest&style=flat-square - :target: https://tox.readthedocs.io/en/latest/?badge=latest - :alt: Documentation status -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/ambv/black - :alt: Code style: black +|Latest version on PyPi| |Supported Python versions| |Azure Pipelines +build status| |Test Coverage| |Documentation status| |Code style: black| + +.. image:: docs/_static/img/tox.png + :target: https://tox.readthedocs.io + :height: 150 + :alt: tox logo + :align: right tox automation project ====================== -**vision: standardize testing in Python** +**Command line driven CI frontend and development task automation tool** + +At its core tox povides a convenient way to run arbitrary commands in +isolated environments to serve as a single entry point for build, test +and release activities. + +tox is highly +`configurable `__ and +`pluggable `__. + +How it works +------------ + +tox creates virtual environments for all configured so called +``testenvs``, it then installs the project and other necessary +dependencies and runs the configured set of commands. + +.. figure:: docs/img/tox_flow.png + :alt: tox flow + + tox flow + +See `system +overview `__ for +more details. + +tox can be used for … +--------------------- + +- creating development environments +- running static code analysis and test tools +- automating package builds +- running tests against the package build by tox +- checking that packages install correctly with different Python + versions/interpreters +- unifying Continuous Integration and command line based testing +- building and deploying project documentation +- releasing a package to PyPI or any other platform +- limit: your imagination + +Usage +----- + +tox is mainly used as a command line tool and needs a ``tox.ini`` or a +``tool.tox`` section in ``pyproject.toml`` containing the configuration. + +A simple example +~~~~~~~~~~~~~~~~ -tox aims to automate and standardize testing in Python. It is part of a larger vision of easing the packaging, testing and release process of Python software. +To test a simple project that has some tests, here is an example with +the ``tox.ini`` in the root of the project: -What is tox? -============ +.. code:: ini -tox is a generic virtualenv management and test command line tool you can use for: + [tox] + envlist = py27,py37 -* checking your package installs correctly with different Python versions and - interpreters + [testenv] + deps = pytest + commands = pytest -* running your tests in each of the environments, configuring your test tool of choice +.. code:: console -* acting as a frontend to Continuous Integration servers, greatly - reducing boilerplate and merging CI and shell-based testing. + $ tox -For more information and the repository please see: + [lots of output from what tox does] + [lots of output from commands that were run] -- home and docs: https://tox.readthedocs.org + __________________ summary _________________ + py27: commands succeeded + py37: commands succeeded + congratulations :) -- repository: https://github.com/tox-dev/tox +tox created two ``testenvs`` - one based on Python2.7 and one based on +Python3.7, it installed pytest in them and ran the tests. The report at +the end summarizes which ``testenvs`` have failed and which have +succeeded. + +.. note:: + + To learn more about what you can do with tox, have a look at + `existing projects using tox `__. + +Documentation +------------- + +Documentation for tox can be found on `Read The Docs `__ + +Communication / questions +------------------------- + +If you have questions about tox you can first check if they have already been answered or are already being discussed on our `issue tracker `__ or on `Stack Overflow `__. + +If you want to discuss topics or propose changes that might not (yet) fit into an issue, you can get in touch via mail through `tox-dev@python.org `__. + +We also have a `Gitter community `__. + +Contributing +------------ + +Contributions are welcome. See +`contributing `__ +and our `Contributor Covenant Code of +Conduct `__. + +Currently the `code `__ and the `issues `__ are hosted on Github. + +The project is licensed under `MIT `__. + +.. |Latest version on PyPi| image:: https://badge.fury.io/py/tox.svg + :target: https://badge.fury.io/py/tox +.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/tox.svg + :target: https://pypi.org/project/tox/ +.. |Azure Pipelines build status| image:: https://dev.azure.com/toxdev/tox/_apis/build/status/tox%20ci?branchName=master + :target: https://dev.azure.com/toxdev/tox/_build/latest?definitionId=9&branchName=master +.. |Test Coverage| image:: https://api.codeclimate.com/v1/badges/425c19ab2169a35e1c16/test_coverage + :target: https://codeclimate.com/github/tox-dev/tox/code?sort=test_coverage +.. |Documentation status| image:: https://readthedocs.org/projects/tox/badge/?version=latest&style=flat-square + :target: https://tox.readthedocs.io/en/latest/?badge=latest +.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/ambv/black From fe7efd8f2b404d134fdf7996537774e23f322d03 Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:00:02 +0100 Subject: [PATCH 2/9] logo to big (height ignored?) try scaling with percentage --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 45666b4fe..fb39b171b 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ build status| |Test Coverage| |Documentation status| |Code style: black| .. image:: docs/_static/img/tox.png :target: https://tox.readthedocs.io - :height: 150 + :scale: 10% :alt: tox logo :align: right From 773a045085b9f4b7c2bf6c04d0c6890790e4b3d0 Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:08:08 +0100 Subject: [PATCH 3/9] try if raw directive works on Github --- README.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index fb39b171b..86a9dfdbb 100644 --- a/README.rst +++ b/README.rst @@ -1,11 +1,15 @@ |Latest version on PyPi| |Supported Python versions| |Azure Pipelines build status| |Test Coverage| |Documentation status| |Code style: black| -.. image:: docs/_static/img/tox.png - :target: https://tox.readthedocs.io - :scale: 10% - :alt: tox logo - :align: right + +.. raw:: html + + + tox logo + tox automation project ====================== From e961effb72fcb3b4e185e4d7b3ed373dc21565b7 Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:13:23 +0100 Subject: [PATCH 4/9] mov example to the top and fix unsupported note directive --- README.rst | 72 ++++++++++++++++++++++++++---------------------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/README.rst b/README.rst index 86a9dfdbb..457208c96 100644 --- a/README.rst +++ b/README.rst @@ -24,6 +24,41 @@ tox is highly `configurable `__ and `pluggable `__. +A simple example +~~~~~~~~~~~~~~~~ + +To test a simple project that has some tests, here is an example with +the ``tox.ini`` in the root of the project: + +.. code:: ini + + [tox] + envlist = py27,py37 + + [testenv] + deps = pytest + commands = pytest + +.. code:: console + + $ tox + + [lots of output from what tox does] + [lots of output from commands that were run] + + __________________ summary _________________ + py27: commands succeeded + py37: commands succeeded + congratulations :) + +tox created two ``testenvs`` - one based on Python2.7 and one based on +Python3.7, it installed pytest in them and ran the tests. The report at +the end summarizes which ``testenvs`` have failed and which have +succeeded. + +**Note:** To learn more about what you can do with tox, have a look at + `existing projects using tox `__. + How it works ------------ @@ -60,43 +95,6 @@ Usage tox is mainly used as a command line tool and needs a ``tox.ini`` or a ``tool.tox`` section in ``pyproject.toml`` containing the configuration. -A simple example -~~~~~~~~~~~~~~~~ - -To test a simple project that has some tests, here is an example with -the ``tox.ini`` in the root of the project: - -.. code:: ini - - [tox] - envlist = py27,py37 - - [testenv] - deps = pytest - commands = pytest - -.. code:: console - - $ tox - - [lots of output from what tox does] - [lots of output from commands that were run] - - __________________ summary _________________ - py27: commands succeeded - py37: commands succeeded - congratulations :) - -tox created two ``testenvs`` - one based on Python2.7 and one based on -Python3.7, it installed pytest in them and ran the tests. The report at -the end summarizes which ``testenvs`` have failed and which have -succeeded. - -.. note:: - - To learn more about what you can do with tox, have a look at - `existing projects using tox `__. - Documentation ------------- From 2390d18600e12e2a313453fc1cbed51cee2e713a Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:17:48 +0100 Subject: [PATCH 5/9] clarify that there is a tox tag on Stack Overflow --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 457208c96..53c25c264 100644 --- a/README.rst +++ b/README.rst @@ -103,7 +103,7 @@ Documentation for tox can be found on `Read The Docs `__ or on `Stack Overflow `__. +If you have questions about tox you can first check if they have already been answered or are already being discussed on our `issue tracker `__ or questions tagged with ``tox`` on `Stack Overflow `__. If you want to discuss topics or propose changes that might not (yet) fit into an issue, you can get in touch via mail through `tox-dev@python.org `__. From 15251e4500d4ca276854107152c7624b9bfa7c9f Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:21:21 +0100 Subject: [PATCH 6/9] whitespace, scale image, move text around a bit. --- README.rst | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 53c25c264..6b082eae4 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,6 @@ |Latest version on PyPi| |Supported Python versions| |Azure Pipelines build status| |Test Coverage| |Documentation status| |Code style: black| - .. raw:: html @@ -27,6 +26,9 @@ tox is highly A simple example ~~~~~~~~~~~~~~~~ +tox is mainly used as a command line tool and needs a ``tox.ini`` or a +``tool.tox`` section in ``pyproject.toml`` containing the configuration. + To test a simple project that has some tests, here is an example with the ``tox.ini`` in the root of the project: @@ -64,16 +66,18 @@ How it works tox creates virtual environments for all configured so called ``testenvs``, it then installs the project and other necessary -dependencies and runs the configured set of commands. - -.. figure:: docs/img/tox_flow.png - :alt: tox flow +dependencies and runs the configured set of commands. See `system +overview `__ +for more details. - tox flow +.. raw:: html -See `system -overview `__ for -more details. + + tox flow + tox can be used for … --------------------- @@ -89,12 +93,6 @@ tox can be used for … - releasing a package to PyPI or any other platform - limit: your imagination -Usage ------ - -tox is mainly used as a command line tool and needs a ``tox.ini`` or a -``tool.tox`` section in ``pyproject.toml`` containing the configuration. - Documentation ------------- From 15fc2533bbc15ebb686146d02bf043aacedb5cce Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:22:42 +0100 Subject: [PATCH 7/9] remove spurious line break --- README.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 6b082eae4..9b99304f7 100644 --- a/README.rst +++ b/README.rst @@ -58,8 +58,7 @@ Python3.7, it installed pytest in them and ran the tests. The report at the end summarizes which ``testenvs`` have failed and which have succeeded. -**Note:** To learn more about what you can do with tox, have a look at - `existing projects using tox `__. +**Note:** To learn more about what you can do with tox, have a look at `existing projects using tox `__. How it works ------------ From 17eed080780ff66aa70489d20c1442b097494fa4 Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 15:26:36 +0100 Subject: [PATCH 8/9] forgot a period --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 9b99304f7..e89637b21 100644 --- a/README.rst +++ b/README.rst @@ -95,7 +95,7 @@ tox can be used for … Documentation ------------- -Documentation for tox can be found on `Read The Docs `__ +Documentation for tox can be found at `Read The Docs `__. Communication / questions ------------------------- From 7f88569c9218a212fe10e5e8507c89a26046c700 Mon Sep 17 00:00:00 2001 From: Oliver Bestwalter Date: Wed, 2 Jan 2019 16:24:41 +0100 Subject: [PATCH 9/9] switch README to markdown (placing / scaling of images possible here) --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 132 ----------------------------------------------------- setup.py | 3 +- tox.ini | 2 + 4 files changed, 132 insertions(+), 133 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 000000000..98d7963d8 --- /dev/null +++ b/README.md @@ -0,0 +1,128 @@ +[![Latest version on +PyPi](https://badge.fury.io/py/tox.svg)](https://badge.fury.io/py/tox) +[![Supported Python +versions](https://img.shields.io/pypi/pyversions/tox.svg)](https://pypi.org/project/tox/) +[![Azure Pipelines build +status](https://dev.azure.com/toxdev/tox/_apis/build/status/tox%20ci?branchName=master)](https://dev.azure.com/toxdev/tox/_build/latest?definitionId=9&branchName=master) +[![Test +Coverage](https://api.codeclimate.com/v1/badges/425c19ab2169a35e1c16/test_coverage)](https://codeclimate.com/github/tox-dev/tox/code?sort=test_coverage) +[![Documentation +status](https://readthedocs.org/projects/tox/badge/?version=latest&style=flat-square)](https://tox.readthedocs.io/en/latest/?badge=latest) +[![Code style: +black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) + + + tox logo + + +# tox automation project + +**Command line driven CI frontend and development task automation tool** + +At its core tox povides a convenient way to run arbitrary commands in +isolated environments to serve as a single entry point for build, test +and release activities. + +tox is highly +[configurable](https://tox.readthedocs.io/en/latest/config.html) and +[pluggable](https://tox.readthedocs.io/en/latest/plugins.html). + +## A simple example + +tox is mainly used as a command line tool and needs a `tox.ini` or a +`tool.tox` section in `pyproject.toml` containing the configuration. + +To test a simple project that has some tests, here is an example with +the `tox.ini` in the root of the project: + +``` {.sourceCode .ini} +[tox] +envlist = py27,py37 + +[testenv] +deps = pytest +commands = pytest +``` + +``` {.sourceCode .console} +$ tox + +[lots of output from what tox does] +[lots of output from commands that were run] + +__________________ summary _________________ + py27: commands succeeded + py37: commands succeeded + congratulations :) +``` + +tox created two `testenvs` - one based on Python2.7 and one based on +Python3.7, it installed pytest in them and ran the tests. The report at +the end summarizes which `testenvs` have failed and which have +succeeded. + +**Note:** To learn more about what you can do with tox, have a look at +[existing projects using +tox](https://github.com/search?l=INI&q=tox.ini+in%3Apath&type=Code). + +### How it works + +tox creates virtual environments for all configured so called +`testenvs`, it then installs the project and other necessary +dependencies and runs the configured set of commands. See [system +overview](https://tox.readthedocs.io/en/latest/#system-overview) for +more details. + + + tox flow + + +### tox can be used for ... + +- creating development environments +- running static code analysis and test tools +- automating package builds +- running tests against the package build by tox +- checking that packages install correctly with different Python + versions/interpreters +- unifying Continuous Integration and command line based testing +- building and deploying project documentation +- releasing a package to PyPI or any other platform +- limit: your imagination + +### Documentation + +Documentation for tox can be found at [Read The Docs](https://tox.readthedocs.org). + +### Communication and questions + +If you have questions about tox you can first check if they have already +been answered or are already being discussed on our [issue +tracker](https://github.com/tox-dev/tox/issues?utf8=%E2%9C%93&q=is%3Aissue+sort%3Aupdated-desc+label%3A%22type%3Aquestion+%3Agrey_question%3A%22+) +or questions tagged with `tox` on [Stack +Overflow](https://stackoverflow.com/questions/tagged/tox). + +If you want to discuss topics or propose changes that might not (yet) +fit into an issue, you can get in touch via mail through +. + +We also have a [Gitter community](https://gitter.im/tox-dev/). + +### Contributing + +Contributions are welcome. See +[contributing](https://github.com/tox-dev/tox/blob/master/CONTRIBUTING.rst) +and our [Contributor Covenant Code of +Conduct](https://github.com/tox-dev/tox/blob/master/CODE_OF_CONDUCT.md). + +Currently the [code](https://github.com/tox-dev/tox) and the +[issues](https://github.com/tox-dev/tox/issues) are hosted on Github. + +The project is licensed under +[MIT](https://github.com/tox-dev/tox/blob/master/LICENSE). diff --git a/README.rst b/README.rst deleted file mode 100644 index e89637b21..000000000 --- a/README.rst +++ /dev/null @@ -1,132 +0,0 @@ -|Latest version on PyPi| |Supported Python versions| |Azure Pipelines -build status| |Test Coverage| |Documentation status| |Code style: black| - -.. raw:: html - - - tox logo - - -tox automation project -====================== - -**Command line driven CI frontend and development task automation tool** - -At its core tox povides a convenient way to run arbitrary commands in -isolated environments to serve as a single entry point for build, test -and release activities. - -tox is highly -`configurable `__ and -`pluggable `__. - -A simple example -~~~~~~~~~~~~~~~~ - -tox is mainly used as a command line tool and needs a ``tox.ini`` or a -``tool.tox`` section in ``pyproject.toml`` containing the configuration. - -To test a simple project that has some tests, here is an example with -the ``tox.ini`` in the root of the project: - -.. code:: ini - - [tox] - envlist = py27,py37 - - [testenv] - deps = pytest - commands = pytest - -.. code:: console - - $ tox - - [lots of output from what tox does] - [lots of output from commands that were run] - - __________________ summary _________________ - py27: commands succeeded - py37: commands succeeded - congratulations :) - -tox created two ``testenvs`` - one based on Python2.7 and one based on -Python3.7, it installed pytest in them and ran the tests. The report at -the end summarizes which ``testenvs`` have failed and which have -succeeded. - -**Note:** To learn more about what you can do with tox, have a look at `existing projects using tox `__. - -How it works ------------- - -tox creates virtual environments for all configured so called -``testenvs``, it then installs the project and other necessary -dependencies and runs the configured set of commands. See `system -overview `__ -for more details. - -.. raw:: html - - - tox flow - - -tox can be used for … ---------------------- - -- creating development environments -- running static code analysis and test tools -- automating package builds -- running tests against the package build by tox -- checking that packages install correctly with different Python - versions/interpreters -- unifying Continuous Integration and command line based testing -- building and deploying project documentation -- releasing a package to PyPI or any other platform -- limit: your imagination - -Documentation -------------- - -Documentation for tox can be found at `Read The Docs `__. - -Communication / questions -------------------------- - -If you have questions about tox you can first check if they have already been answered or are already being discussed on our `issue tracker `__ or questions tagged with ``tox`` on `Stack Overflow `__. - -If you want to discuss topics or propose changes that might not (yet) fit into an issue, you can get in touch via mail through `tox-dev@python.org `__. - -We also have a `Gitter community `__. - -Contributing ------------- - -Contributions are welcome. See -`contributing `__ -and our `Contributor Covenant Code of -Conduct `__. - -Currently the `code `__ and the `issues `__ are hosted on Github. - -The project is licensed under `MIT `__. - -.. |Latest version on PyPi| image:: https://badge.fury.io/py/tox.svg - :target: https://badge.fury.io/py/tox -.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/tox.svg - :target: https://pypi.org/project/tox/ -.. |Azure Pipelines build status| image:: https://dev.azure.com/toxdev/tox/_apis/build/status/tox%20ci?branchName=master - :target: https://dev.azure.com/toxdev/tox/_build/latest?definitionId=9&branchName=master -.. |Test Coverage| image:: https://api.codeclimate.com/v1/badges/425c19ab2169a35e1c16/test_coverage - :target: https://codeclimate.com/github/tox-dev/tox/code?sort=test_coverage -.. |Documentation status| image:: https://readthedocs.org/projects/tox/badge/?version=latest&style=flat-square - :target: https://tox.readthedocs.io/en/latest/?badge=latest -.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/ambv/black diff --git a/setup.py b/setup.py index 23b73abd8..4277edb8f 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,8 @@ setup( name="tox", description="virtualenv-based automation of test activities", - long_description=open("README.rst").read(), + long_description=open("README.md").read(), + long_description_content_type="text/markdown", url="https://tox.readthedocs.org/", use_scm_version={ "write_to": "src/tox/version.py", diff --git a/tox.ini b/tox.ini index ad30c3d2e..219ef4d2b 100644 --- a/tox.ini +++ b/tox.ini @@ -41,6 +41,8 @@ commands = sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_o description = check that the long description is valid basepython = python3.7 deps = twine >= 1.12.1 + # TODO installing readme-renderer[md] should not be necessary + readme-renderer[md] >= 24.0 pip >= 18.0.0 skip_install = true extras =