Adds documentation around cookies_session

docs/features.md

@@ -1,4 +1,6 @@
-# Bake Result
+# Features
+
+## Bake Results
 
 ``cookies.bake()`` returns a result instance with a bunch of fields that
 hold useful information:
@@ -22,4 +24,29 @@ def test_readme(cookies):
     assert readme_lines == ["helloworld", "=========="]
 ```
 
-[path]: https://docs.python.org/3/library/pathlib.html#pathlib.Path
+## Cookies Session
+``cookies_session`` is the same as `cookies` but the instance uses the ["session" scope].
+
+This is useful when you want to run multiple tests on the same cookiecutter instance without having to setup and teardown with each test.
+
+```python
+    @pytest.fixture(scope="module")
+    def bakery(cookies_session):
+        """create a session-wide cookiecutter instance"""
+        result = cookies_session.bake(extra_context={
+            "value_1": "value_1",
+            "value_2": "value_2",
+        })
+        yield result
+
+    def test_session_project_path(bakery):
+        """The first test checks for value 1"""
+        assert bakery.context["value_1"] == "value_1"
+
+    def test_session_same_project_path(bakery):
+        """The second test checks for value 2"""
+        assert bakery.context["value_2"] == "value_2"
+```
+
+[path]: https://docs.python.org/3/library/pathlib.html#pathlib.Path
+["session" scope]: https://docs.pytest.org/en/7.1.x/how-to/fixtures.html?highlight=scope#scope-sharing-fixtures-across-classes-modules-packages-or-session

src/pytest_cookies/plugin.py

@@ -157,14 +157,26 @@ def cookies(request, tmpdir, _cookiecutter_config_file):
 
 @pytest.fixture(scope="session")
 def cookies_session(request, tmpdir_factory, _cookiecutter_config_file):
-    """Yield an instance of the Cookies helper class that can be used to
-    generate a project from a template.
+    """Like `cookies` this yields an instance of the `Cookies` helper class.
+    This instance is scoped at the _session_ level to persist the environment
+    throughout the testing sessioninstead of rebuilding with each referenced test.
 
     Run cookiecutter:
-        result = cookies.bake(extra_context={
-            'variable1': 'value1',
-            'variable2': 'value2',
-        })
+        @pytest.fixture(scope="module")
+        def bakery(cookies_session):
+            """create a session-wide cookiecutter instance"""
+            result = cookies_session.bake(extra_context={
+                "value_1": "value_1",
+                "value_2": "value_2",
+            })
+            yield result
+
+    Call the session in multiple tests:
+        def test_session_project_path(bakery):
+            assert bakery.project_path == "SAME/PATH/"
+
+        def test_session_same_project_path(bakery):
+            assert bakery.project_path == "SAME/PATH/"
     """
     template_dir = request.config.option.template