Add some doc and FAQ about quieting pytest warnings (#172)

As it will take some time and effort to replace the existing yield
tests, add some hopefully helpful information on how to deal with
the warnings.

docs/source/faq.rst

@@ -21,6 +21,16 @@ Is gabbi only for testing Python-based APIs?
 No, you can use :doc:`gabbi-run <runner>` to test an HTTP service
 built in any programming language.
 
+Workarounds
+~~~~~~~~~~~
+
+pytest produces warnings about yield tests. Can I make them stop?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, run as ``py.test --disable-pytest-warnings`` to quiet the
+warnings. Or use a version of pytest less than ``3.0``. For more details
+see :ref:`pytest <pytest_loader>`.
+
 Testing Style
 ~~~~~~~~~~~~~
 

docs/source/loader.rst

@@ -64,6 +64,8 @@ advanced options, including using ``testrepository`` and
 pytest
 ~~~~~~
 
+.. _pytest_loader:
+
 Since pytest does not support the ``load_tests`` system, a different
 way of generating tests is required. A test file must be created
 that calls :meth:`~gabbi.driver.py_test_generator` and yields the
@@ -76,6 +78,15 @@ This can then be run with the usual pytest commands. For example::
 
    py.test -svx pytest-example.py
 
+.. warning:: In ``pytest>=3.0`` yield tests are deprecated and using
+             them will cause pytest to produce a warning. If you
+             wish to ignore and hide these warnings add the
+             ``--disable-pytest-warnings`` parameter to the
+             invocation of ``py.test`` or use a version of pytest
+             earlier than version ``3.0``. A new way of creating gabbi
+             tests that works more effectively with modern pytest is
+             being developed.
+
 .. _source distribution: https://github.com/cdent/gabbi
 .. _the tutorial repo: https://github.com/cdent/gabbi-demo
 .. _pytest: http://pytest.org/