Clarify fixture order and provide images for visual learners

The documentation previously stated that fixture execution
order was dictated by the order fixtures were requested in, but
this isn't a very reliable method controlling fixture order and
can lead to some confusing situations. The only reliable way to
control fixture order is based on scope, fixture dependencies,
and autouse. This reflects that in the documentation, and
provides several examples and images to help clarify that.

Author: Chris NeJame

AUTHORS

@@ -55,6 +55,7 @@ Charles Cloud
 Charles Machalow
 Charnjit SiNGH (CCSJ)
 Chris Lamb
+Chris NeJame
 Christian Boelsen
 Christian Fetzer
 Christian Neumüller

doc/en/example/fixtures/fixture_availability.svg

@@ -0,0 +1,45 @@
+import pytest
+
+
+@pytest.fixture
+def order():
+    return []
+
+
+@pytest.fixture
+def a(order):
+    order.append("a")
+
+
+@pytest.fixture
+def b(a, order):
+    order.append("b")
+
+
+@pytest.fixture(autouse=True)
+def c(b, order):
+    order.append("c")
+
+
+@pytest.fixture
+def d(b, order):
+    order.append("d")
+
+
+@pytest.fixture
+def e(d, order):
+    order.append("e")
+
+
+@pytest.fixture
+def f(e, order):
+    order.append("f")
+
+
+@pytest.fixture
+def g(f, c, order):
+    order.append("g")
+
+
+def test_order_and_g(g, order):
+    assert order == ["a", "b", "c", "d", "e", "f", "g"]

doc/en/example/fixtures/fixture_availability_plugins.svg

@@ -0,0 +1,31 @@
+import pytest
+
+
+@pytest.fixture(scope="class")
+def order():
+    return []
+
+
+@pytest.fixture(scope="class", autouse=True)
+def c1(order):
+    order.append("c1")
+
+
+@pytest.fixture(scope="class")
+def c2(order):
+    order.append("c2")
+
+
+@pytest.fixture(scope="class")
+def c3(order, c1):
+    order.append("c3")
+
+
+class TestClassWithC1Request:
+    def test_order(self, order, c1, c3):
+        assert order == ["c1", "c3"]
+
+
+class TestClassWithoutC1Request:
+    def test_order(self, order, c2):
+        assert order == ["c1", "c2"]