tox.rst: Documentation file for coala in tox

This file ensures that coala is successfully installed in tox properly.

Closes #344

.gitignore

@@ -115,6 +115,9 @@ venv.bak/
 .dmypy.json
 dmypy.json
 
+# Pyre type checker
+.pyre/
+
 # VirtualEnv rules
 # Virtualenv
 # http:https://iamzed.com/2009/05/07/a-primer-on-virtualenv/
@@ -390,17 +393,11 @@ tmtags
 #
 # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
 
-## User settings
-xcuserdata/
-
-## compatibility with Xcode 8 and earlier (ignoring not required starting Xcode 9)
-*.xcscmblueprint
-*.xccheckout
-
-## compatibility with Xcode 3 and earlier (ignoring not required starting Xcode 4)
+## Build generated
 build/
 DerivedData/
-*.moved-aside
+
+## Various settings
 *.pbxuser
 !default.pbxuser
 *.mode1v3
@@ -409,6 +406,68 @@ DerivedData/
 !default.mode2v3
 *.perspectivev3
 !default.perspectivev3
+xcuserdata/
+
+## Other
+*.moved-aside
+*.xccheckout
+*.xcscmblueprint
+
+## Obj-C/Swift specific
+*.hmap
+*.ipa
+*.dSYM.zip
+*.dSYM
+
+## Playgrounds
+timeline.xctimeline
+playground.xcworkspace
+
+# Swift Package Manager
+#
+# Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
+# Packages/
+# Package.pins
+# Package.resolved
+.build/
+
+# CocoaPods
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# Pods/
+#
+# Add this line if you want to avoid checking in source code from the Xcode workspace
+# *.xcworkspace
+
+# Carthage
+#
+# Add this line if you want to avoid checking in source code from Carthage dependencies.
+# Carthage/Checkouts
+
+Carthage/Build
+
+# fastlane
+#
+# It is recommended to not store the screenshots in the git repo. Instead, use fastlane to re-generate the
+# screenshots whenever they are needed.
+# For more information about the recommended setup visit:
+# https://docs.fastlane.tools/best-practices/source-control/#source-control
+
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots/**/*.png
+fastlane/test_output
+
+# Code Injection
+#
+# After new code Injection tools there's a generated folder /iOSInjectionProject
+# https://github.com/johnno1962/injectionforxcode
+
+iOSInjectionProject/
+
 
 # Eclipse rules
 

Users/tox.rst

@@ -0,0 +1,113 @@
+What is Tox?
+===============
+
+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.
+
+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:
+
+::
+
+ # content of: tox.ini , put in same dir as setup.py
+ [tox]
+ envlist = py27,py36
+ [testenv]
+ 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
+
+.. note::
+
+ 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:
+
+::
+
+ tox
+
+.. note::
+
+ 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.
+
+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.
+
+- ``tox`` : This section contains the ``envlist`` which is used to create
+ our dynamic matrix. Refer to the `section here <http: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}``
+
+- ``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.
+
+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``.
+
+Note
+
+For more information about Tox configuration, consult the
+`official documentation <https://tox.readthedocs.io/en/latest/>`_.