Merge pull request #129 from elchupanebrej/feature/doc_alabaster_mobile

Feature/doc alabaster mobile

Author: elchupanebrej

.github/workflows/main.yml

@@ -50,6 +50,8 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "*"
+      - name: Install pandoc
+        uses: r-lib/actions/setup-pandoc@v2
       - name: Install PyPi dependencies
         run: |
           python -m pip install --upgrade pip

.github/workflows/release.yaml

@@ -16,6 +16,8 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.13"
+      - name: Install pandoc
+        uses: r-lib/actions/setup-pandoc@v2
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip build twine

.pre-commit-config.yaml

@@ -1,6 +1,8 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 ---
+default_language_version:
+  python: python3.12
 repos:
   - repo: https://github.com/psf/black
     rev: 24.10.0
@@ -19,7 +21,9 @@ repos:
     rev: v5.0.0
     hooks:
       - id: trailing-whitespace
+        exclude: "^.*\\.rst$"
       - id: end-of-file-fixer
+        exclude: "^.*\\.rst$"
       - id: check-yaml
       - id: check-added-large-files
       - id: check-toml
@@ -56,10 +60,13 @@ repos:
       - id: generate-feature-doc
         name: generate-feature-doc
         entry: >
-          python src/pytest_bdd/script/bdd_tree_to_rst.py
-          features
-          docs/features.rst
+          python src/pytest_bdd/script/bdd_tree_to_rst.py features docs/features
         language: python
         types: [python]
         pass_filenames: false
-        additional_dependencies: ['docopt-ng']
+        additional_dependencies:
+          - 'docopt-ng'
+          - 'pandoc'
+          - 'panflute'
+          - 'pycmarkgfm'
+          - 'pypandoc'

docs/conf.py

@@ -131,6 +131,9 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_css_files = [
+    "css/custom.css",
+]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/features.rst

@@ -0,0 +1,40 @@
+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:
+
+  .. code:: gherkin
+
+     Feature:
+       My Feature description
+       Scenario:
+         Given I check feature description
+
+- And File "conftest.py" with content:
+
+  .. code:: 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
+  ====== ======

docs/features/Feature/Description.feature.rst

@@ -0,0 +1,96 @@
+Feature: Gherkin features autoload
+''''''''''''''''''''''''''''''''''
+
+By default gherkin features are autoloaded and treated as usual pytest
+tests if are placed in the tests hierarchy proposed by pytest. This
+behavior could be disabled
+
+Rule: Feature autoload
+                      
+
+Background:
+           
+
+- Given File "Passing.feature" with content:
+
+  .. code:: gherkin
+
+     Feature: Passing feature
+       Scenario: Passing scenario
+         * Passing step
+
+- Given File "Another.passing.feature.md" with content:
+
+  .. code:: markdown
+
+     # Feature: Passing feature
+     ## Scenario: Passing scenario
+     * Given Passing step
+
+- Given Install npm packages
+
+  ======== =================
+  packages @cucumber/gherkin
+  ======== =================
+  ======== =================
+
+- Given File "conftest.py" with content:
+
+  .. code:: python
+
+     from pytest_bdd import step
+
+     @step('Passing step')
+
+     def _():
+       ...
+
+Scenario: Feature is loaded by default
+                                      
+
+- When run pytest
+- Then pytest outcome must contain tests with statuses:
+
+  +--------+
+  | passed |
+  +========+
+  | 2      |
+  +--------+
+
+Scenario: Feature autoload could be disabled via command line
+                                                             
+
+- When run pytest
+
+  ======== ==========================
+  cli_args --disable-feature-autoload
+  ======== ==========================
+  ======== ==========================
+
+- Then pytest outcome must contain tests with statuses:
+
+  +--------+
+  | passed |
+  +========+
+  | 0      |
+  +--------+
+
+Scenario: Feature autoload could be disabled via pytest.ini
+                                                           
+
+- Given Set pytest.ini content to:
+
+  .. code:: ini
+
+     [pytest]
+     disable_feature_autoload=true
+
+- When run pytest
+
+- Then pytest outcome must contain tests with statuses:
+
+  +--------+
+  | passed |
+  +========+
+  | 0      |
+  +--------+