From 07578be3028c4261e5a0550ebfe9549b1f8c6e23 Mon Sep 17 00:00:00 2001
From: Brad Brown <brad@bradsbrown.com>
Date: Thu, 16 Apr 2020 12:27:31 -0500
Subject: [PATCH] descriptive docstrings, drop dead code

---
 sphinx_gherkindoc/parsers/base.py | 12 +++++++++++-
 tests/test_pytest_writer.py       | 15 +++++++++++----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/sphinx_gherkindoc/parsers/base.py b/sphinx_gherkindoc/parsers/base.py
index 1b452cc..2e1337f 100644
--- a/sphinx_gherkindoc/parsers/base.py
+++ b/sphinx_gherkindoc/parsers/base.py
@@ -8,8 +8,18 @@ def __init__(self, data):
         self._data = data
 
     def __getattr__(self, key):
-        """Grab attribute from wrapped class, if present."""
+        """Grab attribute from wrapped class, if present.
+
+        When inheriting this model,
+        properties may need to be added to the subclass
+        in cases where a specific ``behave`` attribute
+        does not exist on the underlying class,
+        or where the format returned from the underlying attribute
+        does not match the ``behave`` format.
+        """
         if key == "description":
+            # Workaround for current pytest-bdd release (3.2.1),
+            # which does not have a scenario.description attribute.
             return getattr(self._data, key, None)
         return getattr(self._data, key)
 
diff --git a/tests/test_pytest_writer.py b/tests/test_pytest_writer.py
index e367704..24a3dd3 100644
--- a/tests/test_pytest_writer.py
+++ b/tests/test_pytest_writer.py
@@ -26,6 +26,17 @@ def _reformat_keywords(rst_lines):
 
 @pytest.fixture()
 def pytest_rst_output():
+    """Adjust expected rst output to align with pytest-bdd parser formats.
+
+    One change is necessary between ``behave`` and ``pytest-bdd`` formats.
+    Backgrounds and Examples in pytest-bdd do not have descriptions/titles,
+    so "Background: Stuff I Need" will become simply "Background:", for example.
+    As part of this change, the section header underline will also be adjusted
+    to match length.
+
+    This fixture creates a copy of the ``behave`` expected rst output module,
+    with that change made.
+    """
     base_rst_output = SimpleNamespace()
     for attribute in dir(rst_output):
         if not attribute.startswith("_"):
@@ -42,8 +53,6 @@ def feature_file_pytest(tmp_path):
     test_dir = pathlib.Path(__file__).parent
     basic_feature = test_dir / "basic_pytest.feature"
     return basic_feature
-    # with open(test_dir / "basic_pytest.feature") as feature_fo:
-    #     basic_feature.write_text(feature_fo.read())
 
 
 @pytest.fixture()
@@ -51,8 +60,6 @@ def tags_feature_file_pytest(tmp_path):
     test_dir = pathlib.Path(__file__).parent
     tags_feature = test_dir / "tags_pytest.feature"
     return tags_feature
-    # with open(test_dir / "tags_pytest.feature") as feature_fo:
-    #     tags_feature.write_text(feature_fo.read())
 
 
 def pytest_writer(*args, **kwargs):