Merge pull request #118 from elchupanebrej/feature/self_descripting_g…

…herkin Rework documentation structure
elchupanebrej · Oct 6, 2024 · fcf56c9 · fcf56c9
2 parents cc2075f + 96b8249
commit fcf56c9
Show file tree

Hide file tree

Showing 12 changed files with 307 additions and 207 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -44,7 +44,7 @@
 
 # General information about the project.
 project = "Pytest-BDD-NG"
-copyright = "2013-2023, Oleg Pidsadnyi"
+copyright = "2013-2024, Konstantin Goloveshko"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -94,7 +94,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
+html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -227,7 +227,6 @@
         "Pytest-BDD-NG",
         "Pytest-BDD-NG Documentation",
         "Konstantin Goloveshko",
-        "Pytest-BDD-NG",
         "Pytest plugin to execute Gherkin scenarios",
         "Miscellaneous",
     )

diff --git a/docs/features.rst b/docs/features.rst
@@ -1,135 +1,164 @@
+Features
+========
+
 .. NOTE:: Features below are part of end-to-end test suite; You always could find most specific
           use cases of **pytest-bdd-ng** by investigation of its regression
           test suite https://github.com/elchupanebrej/pytest-bdd-ng/tree/default/tests
 
-Tutrorial/Launch.feature
-""""""""""""""""""""""""
 
-.. include:: ../features/Tutrorial/Launch.feature
+
+Scenario
+--------
+
+Description.feature
+###################
+
+.. include:: ../features/Scenario/Description.feature
    :code: gherkin
 
-Feature/Localization.feature
-""""""""""""""""""""""""""""
+Tag.feature
+###########
 
-.. include:: ../features/Feature/Localization.feature
+.. include:: ../features/Scenario/Tag.feature
    :code: gherkin
 
-Feature/Description.feature
-"""""""""""""""""""""""""""
+Outline
+#######
 
-.. include:: ../features/Feature/Description.feature
+Examples Tag.feature
+!!!!!!!!!!!!!!!!!!!!
+
+.. include:: ../features/Scenario/Outline/Examples Tag.feature
    :code: gherkin
 
-Feature/Tag conversion.feature
-""""""""""""""""""""""""""""""
+Step definition
+---------------
 
-.. include:: ../features/Feature/Tag conversion.feature
+Target fixtures specification.feature
+#####################################
+
+.. include:: ../features/Step definition/Target fixtures specification.feature
    :code: gherkin
 
-Feature/Tag.feature
-"""""""""""""""""""
+Pytest fixtures substitution.feature
+####################################
 
-.. include:: ../features/Feature/Tag.feature
+.. include:: ../features/Step definition/Pytest fixtures substitution.feature
    :code: gherkin
 
-Step/Doc string.feature
-"""""""""""""""""""""""
+Parameters
+##########
 
-.. include:: ../features/Step/Doc string.feature
+Defaults.feature
+!!!!!!!!!!!!!!!!
+
+.. include:: ../features/Step definition/Parameters/Defaults.feature
    :code: gherkin
 
-Step/Data table.feature
-"""""""""""""""""""""""
+Injection as fixtures.feature
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step/Data table.feature
+.. include:: ../features/Step definition/Parameters/Injection as fixtures.feature
    :code: gherkin
 
-Step/Step definition bounding.feature
-"""""""""""""""""""""""""""""""""""""
+Conversion.feature
+!!!!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step/Step definition bounding.feature
+.. include:: ../features/Step definition/Parameters/Conversion.feature
    :code: gherkin
 
-Step definition/Target fixtures specification.feature
-"""""""""""""""""""""""""""""""""""""""""""""""""""""
+Parsing by custom parser.feature
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step definition/Target fixtures specification.feature
+.. include:: ../features/Step definition/Parameters/Parsing by custom parser.feature
    :code: gherkin
 
-Step definition/Pytest fixtures substitution.feature
-""""""""""""""""""""""""""""""""""""""""""""""""""""
+Parsing.feature
+!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step definition/Pytest fixtures substitution.feature
+.. include:: ../features/Step definition/Parameters/Parsing.feature
    :code: gherkin
 
-Scenario/Description.feature
-""""""""""""""""""""""""""""
+Step
+----
 
-.. include:: ../features/Scenario/Description.feature
+Doc string.feature
+##################
+
+.. include:: ../features/Step/Doc string.feature
    :code: gherkin
 
-Scenario/Tag.feature
-""""""""""""""""""""
+Data table.feature
+##################
 
-.. include:: ../features/Scenario/Tag.feature
+.. include:: ../features/Step/Data table.feature
    :code: gherkin
 
-Feature/Load/Scenario search from base url.feature
-##################################################
+Step definition bounding.feature
+################################
 
-.. include:: ../features/Feature/Load/Scenario search from base url.feature
+.. include:: ../features/Step/Step definition bounding.feature
    :code: gherkin
 
-Feature/Load/Autoload.feature
-#############################
+Feature
+-------
 
-.. include:: ../features/Feature/Load/Autoload.feature
+Localization.feature
+####################
+
+.. include:: ../features/Feature/Localization.feature
    :code: gherkin
 
-Feature/Load/Scenario function loader.feature
-#############################################
+Description.feature
+###################
 
-.. include:: ../features/Feature/Load/Scenario function loader.feature
+.. include:: ../features/Feature/Description.feature
    :code: gherkin
 
-Feature/Load/Scenario search from base directory.feature
-########################################################
+Tag conversion.feature
+######################
 
-.. include:: ../features/Feature/Load/Scenario search from base directory.feature
+.. include:: ../features/Feature/Tag conversion.feature
    :code: gherkin
 
-Step definition/Parameters/Defaults.feature
-###########################################
+Tag.feature
+###########
 
-.. include:: ../features/Step definition/Parameters/Defaults.feature
+.. include:: ../features/Feature/Tag.feature
    :code: gherkin
 
-Step definition/Parameters/Injection as fixtures.feature
-########################################################
+Load
+####
 
-.. include:: ../features/Step definition/Parameters/Injection as fixtures.feature
+Scenario search from base url.feature
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. include:: ../features/Feature/Load/Scenario search from base url.feature
    :code: gherkin
 
-Step definition/Parameters/Conversion.feature
-#############################################
+Autoload.feature
+!!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step definition/Parameters/Conversion.feature
+.. include:: ../features/Feature/Load/Autoload.feature
    :code: gherkin
 
-Step definition/Parameters/Parsing by custom parser.feature
-###########################################################
+Scenario function loader.feature
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step definition/Parameters/Parsing by custom parser.feature
+.. include:: ../features/Feature/Load/Scenario function loader.feature
    :code: gherkin
 
-Step definition/Parameters/Parsing.feature
-##########################################
+Scenario search from base directory.feature
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-.. include:: ../features/Step definition/Parameters/Parsing.feature
+.. include:: ../features/Feature/Load/Scenario search from base directory.feature
    :code: gherkin
 
-Scenario/Outline/Examples Tag.feature
-#####################################
+Tutrorial
+---------
 
-.. include:: ../features/Scenario/Outline/Examples Tag.feature
+Launch.feature
+##############
+
+.. include:: ../features/Tutrorial/Launch.feature
    :code: gherkin
diff --git a/features/Feature/Localization.feature b/features/Feature/Localization.feature
@@ -1,5 +1,6 @@
 Feature: Scenarios tags could be localized
-  pytest-bdd-ng supports all localizations which Gherkin does: https://cucumber.io/docs/gherkin/languages/
+  pytest-bdd-ng supports all localizations which
+  Gherkin does: https://cucumber.io/docs/gherkin/languages/
 
   Scenario:
       Given File "Localized.feature" with content:

diff --git a/features/Scenario/Description.feature b/features/Scenario/Description.feature
@@ -1,7 +1,9 @@
 Feature: Descriptions
-  Free-form descriptions can be placed underneath Feature, Example/Scenario, Background, Scenario Outline and Rule.
+  Free-form descriptions can be placed
+  underneath Feature, Example/Scenario, Background, Scenario Outline and Rule.
   You can write anything you like, as long as no line starts with a keyword.
-  Descriptions can be in the form of Markdown - formatters including the official HTML formatter support this.
+  Descriptions can be in the form of Markdown - formatters including
+  the official HTML formatter support this.
 
   Scenario:
       Given File "Description.feature" with content:

diff --git a/features/Step definition/Parameters/Conversion.feature b/features/Step definition/Parameters/Conversion.feature
@@ -30,7 +30,8 @@ Feature: Step definitions parameters conversion
       |     1|
 
   Rule: for anonymous groups
-    Step definitions parameters could not have a name, so we have to name them before conversion
+    Step definitions parameters could not have a name, so
+    we have to name them before conversion
 
     Scenario:
       Given File "conftest.py" with content:
@@ -42,7 +43,11 @@ Feature: Step definitions parameters conversion
         class Item(Enum):
           CUCUMBER = 'cucumber'
 
-        @given(parse(r"I have a (\w+)"), anonymous_group_names=('item',), converters=dict(item=Item))
+        @given(
+          parse(r"I have a (\w+)"),
+          anonymous_group_names=('item',),
+          converters=dict(item=Item)
+        )
         def i_have_item(item):
             assert item == Item.CUCUMBER
         """
@@ -60,12 +65,19 @@ Feature: Step definitions parameters conversion
         from cucumber_expressions.expression import CucumberExpression
         from cucumber_expressions.parameter_type_registry import ParameterTypeRegistry
 
-        parse = partial(CucumberExpression, parameter_type_registry = ParameterTypeRegistry())
+        parse = partial(
+          CucumberExpression,
+          parameter_type_registry = ParameterTypeRegistry()
+        )
 
         class Item(Enum):
           CUCUMBER = 'cucumber'
 
-        @given(parse(r"I have a {word}"), anonymous_group_names=('item',), converters=dict(item=Item))
+        @given(
+          parse(r"I have a {word}"),
+          anonymous_group_names=('item',),
+          converters=dict(item=Item)
+        )
         def i_have_item(item):
             assert item == Item.CUCUMBER
         """

diff --git a/features/Step definition/Parameters/Defaults.feature b/features/Step definition/Parameters/Defaults.feature
@@ -27,7 +27,11 @@ Feature: Step definitions parameters could have default values
         return [Freshness.FRESH, Freshness.ROTTEN, Freshness.FRESH, Freshness.SALTED]
 
       @given("I have a pickle", param_defaults=dict(freshness=Freshness.SALTED))
-      @given(parse(r"I have a ((?P<freshness>\w+)\s)?cucumber"), converters=dict(freshness=Freshness), param_defaults=dict(freshness=Freshness.FRESH))
+      @given(
+        parse(r"I have a ((?P<freshness>\w+)\s)?cucumber"),
+        converters=dict(freshness=Freshness),
+        param_defaults=dict(freshness=Freshness.FRESH)
+      )
       def i_have_cucumber(freshness, oracle_freshness):
           assert freshness == oracle_freshness.pop(0)
       """