Rework documentation structure

Features/Feature/Description.feature

@@ -0,0 +1,26 @@
+Feature: Descriptions
+  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.
+
+  Scenario:
+      Given File "Description.feature" with content:
+        """gherkin
+        Feature:
+          My Feature description
+          Scenario:
+            Given I check feature description
+
+        """
+      And File "conftest.py" with content:
+        """python
+        from pytest_bdd import given
+
+        @given('I check feature description')
+        def step(feature):
+          assert feature.description == "My Feature description"
+        """
+      When run pytest
+      Then pytest outcome must contain tests with statuses:
+        |passed|failed|
+        |     1|     0|

Features/Feature and scenario could have descriptions.feature → Features/Scenario/Description.feature

@@ -7,21 +7,15 @@ Feature: Descriptions
       Given File "Description.feature" with content:
         """gherkin
         Feature:
-          My Feature description
           Scenario:
             My Scenario description
 
-            Given I check feature description
             Given I check scenario description
         """
       And File "conftest.py" with content:
         """python
         from pytest_bdd import given
 
-        @given('I check feature description')
-        def step(feature):
-          assert feature.description == "My Feature description"
-
         @given('I check scenario description')
         def step(scenario):
           assert "My Scenario description" in scenario.description

docs/features.rst

@@ -1,129 +1,135 @@
-.. 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
-
-Feature tags.feature
-!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Feature tags.feature
-   :code: gherkin
-
-Feature and scenario could have descriptions.feature
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Feature and scenario could have descriptions.feature
-   :code: gherkin
-
-Tutorial launch.feature
-!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Tutorial launch.feature
-   :code: gherkin
-
-Feature tag conversion.feature
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Feature tag conversion.feature
-   :code: gherkin
-
-Steps could have data tables.feature
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Steps could have data tables.feature
-   :code: gherkin
-
-Feature localization.feature
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Feature localization.feature
-   :code: gherkin
-
-Steps to step definition bounding.feature
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Steps to step definition bounding.feature
-   :code: gherkin
-
-Steps could have doc strings.feature
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-.. include:: ../Features/Steps could have doc strings.feature
-   :code: gherkin
-
-Step define target fixtures.feature
-"""""""""""""""""""""""""""""""""""
-
-.. include:: ../Features/Step definition/Step define target fixtures.feature
-   :code: gherkin
-
-Step utilize fixtures.feature
-"""""""""""""""""""""""""""""
-
-.. include:: ../Features/Step definition/Step utilize fixtures.feature
-   :code: gherkin
-
-Scenario search from base url.feature
-"""""""""""""""""""""""""""""""""""""
-
-.. include:: ../Features/Load/Scenario search from base url.feature
-   :code: gherkin
-
-Autoload.feature
-""""""""""""""""
-
-.. include:: ../Features/Load/Autoload.feature
-   :code: gherkin
-
-Scenario function loader.feature
-""""""""""""""""""""""""""""""""
-
-.. include:: ../Features/Load/Scenario function loader.feature
-   :code: gherkin
-
-Scenario search from base directory.feature
-"""""""""""""""""""""""""""""""""""""""""""
-
-.. include:: ../Features/Load/Scenario search from base directory.feature
-   :code: gherkin
-
-Scenario tags.feature
-"""""""""""""""""""""
-
-.. include:: ../Features/Scenario/Scenario tags.feature
-   :code: gherkin
-
-Defaults.feature
-################
-
-.. include:: ../Features/Step definition/Parameters/Defaults.feature
-   :code: gherkin
-
-Injection as fixtures.feature
-#############################
-
-.. include:: ../Features/Step definition/Parameters/Injection as fixtures.feature
-   :code: gherkin
-
-Conversion.feature
-##################
-
-.. include:: ../Features/Step definition/Parameters/Conversion.feature
-   :code: gherkin
-
-Parsing by custom parser.feature
-################################
-
-.. include:: ../Features/Step definition/Parameters/Parsing by custom parser.feature
-   :code: gherkin
-
-Parsing.feature
-###############
-
-.. include:: ../Features/Step definition/Parameters/Parsing.feature
-   :code: gherkin
-
-Tags for Scenario Outlines examples.feature
-###########################################
-
-.. include:: ../Features/Scenario/Outline/Tags for Scenario Outlines examples.feature
-   :code: gherkin
+.. 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
+
+Feature\Description.feature
+"""""""""""""""""""""""""""
+
+.. include:: ../Features/Feature/Description.feature
+   :code: gherkin
+
+Feature\Localization.feature
+""""""""""""""""""""""""""""
+
+.. include:: ../Features/Feature/Localization.feature
+   :code: gherkin
+
+Feature\Tag conversion.feature
+""""""""""""""""""""""""""""""
+
+.. include:: ../Features/Feature/Tag conversion.feature
+   :code: gherkin
+
+Feature\Tag.feature
+"""""""""""""""""""
+
+.. include:: ../Features/Feature/Tag.feature
+   :code: gherkin
+
+Scenario\Description.feature
+""""""""""""""""""""""""""""
+
+.. include:: ../Features/Scenario/Description.feature
+   :code: gherkin
+
+Scenario\Tag.feature
+""""""""""""""""""""
+
+.. include:: ../Features/Scenario/Tag.feature
+   :code: gherkin
+
+Step\Data table.feature
+"""""""""""""""""""""""
+
+.. include:: ../Features/Step/Data table.feature
+   :code: gherkin
+
+Step\Doc string.feature
+"""""""""""""""""""""""
+
+.. include:: ../Features/Step/Doc string.feature
+   :code: gherkin
+
+Step\Step definition bounding.feature
+"""""""""""""""""""""""""""""""""""""
+
+.. include:: ../Features/Step/Step definition bounding.feature
+   :code: gherkin
+
+Step definition\Pytest fixtures substitution.feature
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. include:: ../Features/Step definition/Pytest fixtures substitution.feature
+   :code: gherkin
+
+Step definition\Target fixtures specification.feature
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. include:: ../Features/Step definition/Target fixtures specification.feature
+   :code: gherkin
+
+Tutrorial\Launch.feature
+""""""""""""""""""""""""
+
+.. include:: ../Features/Tutrorial/Launch.feature
+   :code: gherkin
+
+Feature\Load\Autoload.feature
+#############################
+
+.. include:: ../Features/Feature/Load/Autoload.feature
+   :code: gherkin
+
+Feature\Load\Scenario function loader.feature
+#############################################
+
+.. include:: ../Features/Feature/Load/Scenario function loader.feature
+   :code: gherkin
+
+Feature\Load\Scenario search from base directory.feature
+########################################################
+
+.. include:: ../Features/Feature/Load/Scenario search from base directory.feature
+   :code: gherkin
+
+Feature\Load\Scenario search from base url.feature
+##################################################
+
+.. include:: ../Features/Feature/Load/Scenario search from base url.feature
+   :code: gherkin
+
+Scenario\Outline\Examples Tag.feature
+#####################################
+
+.. include:: ../Features/Scenario/Outline/Examples Tag.feature
+   :code: gherkin
+
+Step definition\Parameters\Conversion.feature
+#############################################
+
+.. include:: ../Features/Step definition/Parameters/Conversion.feature
+   :code: gherkin
+
+Step definition\Parameters\Defaults.feature
+###########################################
+
+.. include:: ../Features/Step definition/Parameters/Defaults.feature
+   :code: gherkin
+
+Step definition\Parameters\Injection as fixtures.feature
+########################################################
+
+.. include:: ../Features/Step definition/Parameters/Injection as fixtures.feature
+   :code: gherkin
+
+Step definition\Parameters\Parsing by custom parser.feature
+###########################################################
+
+.. include:: ../Features/Step definition/Parameters/Parsing by custom parser.feature
+   :code: gherkin
+
+Step definition\Parameters\Parsing.feature
+##########################################
+
+.. include:: ../Features/Step definition/Parameters/Parsing.feature
+   :code: gherkin

src/pytest_bdd/script/bdd_tree_to_rst.py

@@ -48,11 +48,12 @@ def convert(features_path: Path, output_file_path: Path):
         sub_processable_paths = list(filter(methodcaller("is_dir"), processable_path.iterdir()))
 
         for path in gherkin_file_paths:
+            rel_path = path.relative_to(features_path)
             content += dedent(
                 # language=rst
                 f"""\
-                    {path.name}
-                    {SECTION_SYMBOLS[len(path.relative_to(features_path).parts)-1]*len(path.name)}
+                    {rel_path}
+                    {SECTION_SYMBOLS[len(rel_path.parts)-1]*len(str(rel_path))}
 
                     .. include:: {(output_path_rel_to_features_path / path.relative_to(features_path)).as_posix()}
                        :code: gherkin
@@ -61,11 +62,12 @@ def convert(features_path: Path, output_file_path: Path):
             )
 
         for path in struct_bdd_file_paths:
+            rel_path = path.relative_to(features_path)
             content += dedent(
                 # language=rst
                 f"""\
-                    {path.name}
-                    {SECTION_SYMBOLS[len(path.relative_to(features_path).parts)-1]*len(path.name)}
+                    {rel_path}
+                    {SECTION_SYMBOLS[len(rel_path.parts)-1]*len(str(rel_path))}
 
                     .. include:: {(output_path_rel_to_features_path / path.relative_to(features_path)).as_posix()}
                        :code: yaml

tests/doc/test_doc.py

@@ -42,8 +42,8 @@ def test_doc_generation(testdir: "Testdir"):
             .. include:: features/simple.gherkin
                :code: gherkin
 
-            other_simple.gherkin
-            """"""""""""""""""""
+            extra\\other_simple.gherkin
+            """"""""""""""""""""""""""
 
             .. include:: features/extra/other_simple.gherkin
                :code: gherkin