Skip to content

Commit

Permalink
tox.rst: Documentation file for coala in tox
Browse files Browse the repository at this point in the history 
This file ensures that coala is successfully installed in tox properly.

Closes coala#344
  • Loading branch information
@ManthanKeim
ManthanKeim committed Nov 26, 2018
1 parent 9e1647a commit cba03b4
Showing 1 changed file with 75 additions and 73 deletions.
148 changes: 75 additions & 73 deletions Users/tox.rst
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,25 @@
What is Tox?
== == == == == == == =
tox is a generic virtualenv management and test command line tool you can use for:
===============

tox is a generic virtualenv management and test command line tool you can use
for:

- checking your package installs correctly with different Python versions and
interpreters
- running your tests in each of the environments, configuring your test tool
of choice
- acting as a frontend to Continuous Integration servers, greatly reducing
boilerplate and merging CI and shell-based testing.

- checking your package installs correctly with different Python versions and interpreters
- running your tests in each of the environments, configuring your test tool of choice
- acting as a frontend to Continuous Integration servers, greatly reducing boilerplate and merging CI and shell-based testing.

taken from `tox.readthedocs.io <https://tox.readthedocs.io/en/latest/>`__.

Basic example.
----------------------------------------------------------------
First, install tox with pip install tox. Then put basic information about your project and the test
environments you want your project to run in into a tox.ini file residing right next to your setup.py file:
First, install tox with pip install tox. Then put basic information about
your project and the test
environments you want your project to run in into a tox.ini file residing
right next to your setup.py file:

::

Expand All @@ -20,100 +28,94 @@ environments you want your project to run in into a tox.ini file residing right
envlist = py27,py36

[testenv]
deps = pytest # install pytest in the virtualenv where commands will be executed
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
pytest # or any other test runner that you might use
.. Note ::
Note

You can also try generating a tox.ini file automatically, by running tox-quickstart
and then answering a few simple questions.
You can also try generating a tox.ini file automatically, by running
tox-quickstart and then answering a few simple questions.

To sdist-package, install and test your project against Python2.7 and Python3.6, just type:
To sdist-package, install and test your project against Python2.7 and
Python3.6, just type:

::

tox

and watch things happening (you must have python2.7 and python3.6 installed in your environment
otherwise you will see errors). When you run tox a second time you’ll note that it runs much faster
because it keeps track of virtualenv details and will not recreate or re-install dependencies.
You also might want to checkout tox configuration and usage examples to get some more ideas.

Environment variables
---------------------

When running ``tox`` we've allowed for the usage of environment variables to tweak certain settings
of the playbook run using Ansible's ``--extra-vars``. It's helpful in Jenkins jobs or for manual test
runs of ``ceph-ansible``.

The following environent variables are available for use:

* ``FETCH_DIRECTORY`` : (default: ``changedir``) This would configure the ``ceph-ansible`` variable ``fetch_directory``. This defaults to
the ``changedir`` of the given scenario and should not need to be changed.

* ``CEPH_STABLE_RELEASE``: (default: ``jewel``) This would configure the ``ceph-ansible`` variable ``ceph_stable_relese``. This is set
automatically when using the ``jewel-*`` or ``kraken-*`` testing scenarios.

* ``UPDATE_CEPH_STABLE_RELEASE``: (default: ``kraken``) This would configure the ``ceph-ansible`` variable ``ceph_stable_relese`` during an ``update``
scenario. This is set automatically when using the ``jewel-*`` or ``kraken-*`` testing scenarios.

* ``CEPH_DOCKER_REGISTRY``: (default: ``docker.io``) This would configure the ``ceph-ansible`` variable ``ceph_docker_registry``.

* ``CEPH_DOCKER_IMAGE``: (default: ``ceph/daemon``) This would configure the ``ceph-ansible`` variable ``ceph_docker_image``.

* ``CEPH_DOCKER_IMAGE_TAG``: (default: ``latest``) This would configure the ``ceph-ansible`` variable ``ceph_docker_image_name``.

* ``CEPH_DEV_BRANCH``: (default: ``master``) This would configure the ``ceph-ansible`` variable ``ceph_dev_branch`` which defines which branch we'd
like to install from shaman.ceph.com.

* ``CEPH_DEV_SHA1``: (default: ``latest``) This would configure the ``ceph-ansible`` variable ``ceph_dev_sha1`` which defines which sha1 we'd like
to install from shaman.ceph.com.

* ``UPDATE_CEPH_DEV_BRANCH``: (default: ``master``) This would configure the ``ceph-ansible`` variable ``ceph_dev_branch`` which defines which branch we'd
like to update to from shaman.ceph.com.

* ``UPDATE_CEPH_DEV_SHA1``: (default: ``latest``) This would configure the ``ceph-ansible`` variable ``ceph_dev_sha1`` which defines which sha1 we'd like
to update to from shaman.ceph.com.

and watch things happening (you must have python2.7 and python3.6 installed
in your environment
otherwise you will see errors). When you run tox a second time you’ll note
that it runs much faster
because it keeps track of virtualenv details and will not recreate or
re-install dependencies.
You also might want to checkout tox configuration and usage examples to get
some more ideas.

.. _tox_sections:

Sections
--------

The ``tox.ini`` file has a number of top level sections defined by ``[ ]`` and subsections within those. For complete documentation
on all subsections inside of a tox section please refer to the tox documentation.
The ``tox.ini`` file has a number of top level sections defined by ``[ ]``
and subsections within those. For complete documentation
on all subsections inside of a tox section please refer to the tox
documentation.

* ``tox`` : This section contains the ``envlist`` which is used to create our dynamic matrix. Refer to the `section here <https://tox.readthedocs.io/en/latest/config.html#generating-environments-conditional-settings>`_ for more information on how the ``envlist`` works.
- ``tox`` : This section contains the ``envlist`` which is used to create
our dynamic matrix. Refer to the `section here <https://tox.readthedocs.io/
en/latest/config.html#generating-environments-conditional-settings>`_ for
more information on how the ``envlist`` works.

* ``purge`` : This section contains commands that only run for scenarios that purge the cluster and redeploy. You'll see this section being reused in ``testenv``
with the following syntax: ``{[purge]commands}``
- ``purge`` : This section contains commands that only run for scenarios
that purge the cluster and redeploy. You'll see this section being reused in
``testenv``with the following syntax: ``{[purge]commands}``

* ``update`` : This section contains commands taht only run for scenarios that deploy a cluster and then upgrade it to another Ceph version.
- ``update`` : This section contains commands taht only run for scenarios
that
deploy a cluster and then upgrade it to another Ceph version.

* ``testenv`` : This is the main section of the ``tox.ini`` file and is run on every scenario. This section contains many *factors* that define conditional
settings depending on the scenarios defined in the ``envlist``. For example, the factor ``centos7_cluster`` in the ``changedir`` subsection of ``testenv`` sets
the directory that tox will change do when that factor is selected. This is an important behavior that allows us to use the same ``tox.ini`` and reuse commands while
tweaking certain sections per testing scenario.
- ``testenv`` : This is the main section of the ``tox.ini`` file and is run
on every scenario. This section contains many *factors* that define
conditional settings depending on the scenarios defined in the ``envlist``.
For example, the factor``centos7_cluster`` in the ``changedir`` subsection
of ``testenv`` sets the directory that tox will change do when that factor
is selected. This is an important behavior that allows us to use the same
``tox.ini`` and reuse commands while tweaking certain sections per testing
scenario.


.. _tox_environments:

Modifying or Adding environments
--------------------------------

The tox environments are controlled by the ``envlist`` subsection of the ``[tox]`` section. Anything inside of ``{}`` is considered a *factor* and will be included
in the dynamic matrix that tox creates. Inside of ``{}`` you can include a comma separated list of the *factors*. Do not use a hyphen (``-``) as part
of the *factor* name as those are used by tox as the separator between different factor sets.

For example, if wanted to add a new test *factor* for the next Ceph release of luminious this is how you'd accomplish that. Currently, the first factor set in our ``envlist``
is used to define the Ceph release (``{jewel,kraken,rhcs}-...``). To add luminous you'd change that to look like ``{luminous,kraken,rhcs}-...``. In the ``testenv`` section
this is a subsection called ``setenv`` which allows you to provide environment variables to the tox environment and we support an environment variable called ``CEPH_STABLE_RELEASE``.
To ensure that all the new tests that are created by adding the luminous *factor* you'd do this in that section: ``luminous: CEPH_STABLE_RELEASE=luminous``.
The tox environments are controlled by the ``envlist`` subsection of the
``[tox]`` section. Anything inside of ``{}`` is considered a *factor* and
will be included
in the dynamic matrix that tox creates. Inside of ``{}`` you can include
a comma separated list of the *factors*. Do not use a hyphen (``-``) as part
of the *factor* name as those are used by tox as the separator between
different factor sets.

For example, if wanted to add a new test *factor* for the next Ceph
release of luminious this is how you'd accomplish that. Currently, the first
factor set in our ``envlist``
is used to define the Ceph release (``{jewel,kraken,rhcs}-...``). To add
luminous you'd change that to look like ``{luminous,kraken,rhcs}-...``.
In the ``testenv`` section
this is a subsection called ``setenv`` which allows you to provide environment
variables to the tox environment and we support an environment variable
called ``CEPH_STABLE_RELEASE``.
To ensure that all the new tests that are created by adding the luminous
*factor* you'd do this in that section:
``luminous: CEPH_STABLE_RELEASE=luminous``.

Note


For more information about Tox configuration, consult the `official documentation <https://tox.readthedocs.io/en/latest/>`__.
For more information about Tox configuration, consult the
`official documentation <https://tox.readthedocs.io/en/latest/>`__.

0 comments on commit cba03b4

Please sign in to comment.