Merge pull request #3336 from nicoddemus/filter-warnings-ref-doc

Add missing reference doc for filterwarnings mark

doc/en/reference.rst

@@ -94,6 +94,31 @@ Marks can be used apply meta data to *test functions* (but not fixtures), which
 fixtures or plugins.
 
 
+.. _`pytest.mark.filterwarnings ref`:
+
+pytest.mark.filterwarnings
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`filterwarnings`.
+
+Add warning filters to marked test items.
+
+.. py:function:: pytest.mark.filterwarnings(filter)
+
+    :keyword str filter:
+        A *warning specification string*, which is composed of contents of the tuple ``(action, message, category, module, lineno)``
+        as specified in `The Warnings filter <https://docs.python.org/3/library/warnings.html#warning-filter>`_ section of
+        the Python documentation, separated by ``":"``. Optional fields can be omitted.
+
+        For example:
+
+        .. code-block:: python
+
+            @pytest.mark.warnings("ignore:.*usage will be deprecated.*:DeprecationWarning")
+            def test_foo():
+                ...
+
+
 .. _`pytest.mark.parametrize ref`:
 
 pytest.mark.parametrize

doc/en/warnings.rst

@@ -78,6 +78,9 @@ Both ``-W`` command-line option and ``filterwarnings`` ini option are based on P
 `-W option`_ and `warnings.simplefilter`_, so please refer to those sections in the Python
 documentation for other examples and advanced usage.
 
+
+.. _`filterwarnings`:
+
 ``@pytest.mark.filterwarnings``
 -------------------------------