From d7b722e2ae6dbf4b10bbba14c3a2dc5c4f2738b4 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Fri, 6 Jul 2018 20:55:42 -0300
Subject: [PATCH 1/2] Add reference docs for pytest.mark.usefixtures

---
 doc/en/reference.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index fe9e87042..cdae37f95 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -161,6 +161,20 @@ Skip a test function if a condition is ``True``.
     :keyword str reason: Reason why the test function is being skipped.
 
 
+.. _`pytest.mark.usefixtures ref`:
+
+pytest.mark.usefixtures
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`usefixtures`.
+
+Mark a test function as using the given fixture names.
+
+.. py:function:: pytest.mark.usefixtures(*names)
+
+    :param args: the names of the fixture to use as strings
+
+
 .. _`pytest.mark.xfail ref`:
 
 pytest.mark.xfail

From d26a596072c4b83340904512d5d34a107daf13eb Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Sat, 7 Jul 2018 10:01:10 -0300
Subject: [PATCH 2/2] Add a warning about usefixtures mark not working in
 fixtures

Fix #1014
---
 doc/en/fixture.rst   | 18 +++++++++++++++++-
 doc/en/reference.rst |  7 ++++++-
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst
index e07d00eaa..301bcee4c 100644
--- a/doc/en/fixture.rst
+++ b/doc/en/fixture.rst
@@ -943,7 +943,7 @@ a generic feature of the mark mechanism:
 Note that the assigned variable *must* be called ``pytestmark``, assigning e.g.
 ``foomark`` will not activate the fixtures.
 
-Lastly you can put fixtures required by all tests in your project
+It is also possible to put fixtures required by all tests in your project
 into an ini-file:
 
 .. code-block:: ini
@@ -953,6 +953,22 @@ into an ini-file:
     usefixtures = cleandir
 
 
+.. warning::
+
+    Note this mark has no effect in **fixture functions**. For example,
+    this **will not work as expected**:
+
+    .. code-block:: python
+
+        @pytest.mark.usefixtures("my_other_fixture")
+        @pytest.fixture
+        def my_fixture_that_sadly_wont_use_my_other_fixture():
+            ...
+
+    Currently this will not generate any error or warning, but this is intended
+    to be handled by `#3664 <https://github.com/pytest-dev/pytest/issues/3664>`_.
+
+
 .. _`autouse`:
 .. _`autouse fixtures`:
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index cdae37f95..b65e15822 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -170,9 +170,14 @@ pytest.mark.usefixtures
 
 Mark a test function as using the given fixture names.
 
+.. warning::
+
+    This mark can be used with *test functions* only, having no affect when applied
+    to a **fixture** function.
+
 .. py:function:: pytest.mark.usefixtures(*names)
 
-    :param args: the names of the fixture to use as strings
+    :param args: the names of the fixture to use, as strings
 
 
 .. _`pytest.mark.xfail ref`: