diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index f28b8166b..dab832c9a 100644
--- a/doc/en/reference.rst
+++ b/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
@@ -991,7 +1016,7 @@ passed multiple times. The expected format is ``name=value``. For example::
     .. code-block:: ini
 
         [pytest]
-        log_cli_level = INFO 
+        log_cli_level = INFO
 
     For more information, see :ref:`live_logs`.
 
diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index df61e1f38..e78a6afc0 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -25,14 +25,14 @@ Running pytest now produces this output::
     platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y
     rootdir: $REGENDOC_TMPDIR, inifile:
     collected 1 item
-    
+
     test_show_warnings.py .                                              [100%]
-    
+
     ============================= warnings summary =============================
     test_show_warnings.py::test_one
       $REGENDOC_TMPDIR/test_show_warnings.py:4: UserWarning: api v1, should use functions from v2
         warnings.warn(UserWarning("api v1, should use functions from v2"))
-    
+
     -- Docs: http://doc.pytest.org/en/latest/warnings.html
     =================== 1 passed, 1 warnings in 0.12 seconds ===================
 
@@ -45,17 +45,17 @@ them into errors::
     F                                                                    [100%]
     ================================= FAILURES =================================
     _________________________________ test_one _________________________________
-    
+
         def test_one():
     >       assert api_v1() == 1
-    
-    test_show_warnings.py:8: 
-    _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
-    
+
+    test_show_warnings.py:8:
+    _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
+
         def api_v1():
     >       warnings.warn(UserWarning("api v1, should use functions from v2"))
     E       UserWarning: api v1, should use functions from v2
-    
+
     test_show_warnings.py:4: UserWarning
     1 failed in 0.12 seconds
 
@@ -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``
 -------------------------------