Take @step string from implementation docstring about behave HOT 10 CLOSED

Interesting idea. Would it be a better trick to just see if the step function has a docstring and use it if there?

from behave.

Sure, even easier! Just needs to be a way to generate documentation for the steps for the people writing the Gherkin features, who don't necessarily want to read the Python source code.

from behave.

Having had a think about this, I'm not sure. I put together some code that uses the step decorator to add stuff to the docstring but I'm not sure whether it's a good idea or not. I'm also not sure if it addresses your issue or not.

Further thought is needed.

from behave.

The decorator definitely should not modify the docstring. The suggestion was for the decorator to use the first line of the docstring as the step pattern, rather than passing it directly to the decorator. If there is no docstring then revert to current behaviour where decorator expects to get the step pattern.

The idea was to make it easier to maintain documentation of available steps by including them in docstrings that are used by documentation generators like Sphinx. It's important for those writing features to see what steps are available and what they do without having to read the code.

from behave.

Maybe a command line option on behave to dump steps (plus docstrings) to a reStructured text file, instead?

from behave.

While I like the idea of documenting step_functions and Gherkin given/when/then steps, I do not like the suggested solution.
The current decorator syntax is currently heavily used in different BDD test frameworks.
It serves just one purpose: Providing the glue (regexp syntax) to bind textual BDD steps to step_functions (implementations).
In addition, the decorator syntax is concise, easy readable and understandable.

Maybe a special tool, similar to sphinx-autogen, is a better idea.
It could collect the step_functions and generate *.rst files.

from behave.

An extension to Sphinx would be perfect.

from behave.

How about a command line option to behave that will generate the steps documentation at the same time as running the tests?

from behave.

@quantoid
A "steps.doc" formatter (and related step definitions formatters) is in the works that will show the documentation (doc-strings) of the available step definitions in dry-run mode (for immediate feedback without need of running the tests). This should implement the primary intention of this change-request. The initial idea of using the first line of the doc-string for the step definition (matcher line) is rejected.

EXAMPLE:

$ behave --dry-run -f steps.doc features/
@given('{person} lives in {city}')
  Function: step_given_person_lives_in_city()
  Location: features/steps/alice_steps.py:3
    Setup the data where a person lives and store in the database.

    :param person:  Person's name (as string).
    :param city:    City where the person lives (as string).

@when('I visit {person}')
  Function: step_when_visit_person()
  Location: features/steps/alice_steps.py:16

@then('I meet {person} in {city}')
  Function: step_then_meet_person_in_city()
  Location: features/steps/alice_steps.py:21
    Checks if I can meet the person in the expected city.

    :param person:  Person's name as key (as string).
    :param city:    Expected city (as string).

@step('a step passes')
  Function: step_passes()
  Location: features/steps/passing_steps.py:3
    This step always passes.
...

A sphinx-based documentation generator, that was discussed here, will be provided at a later stage. It could be an extra tool (preferred) or could be provided as a formatter.

from behave.

Sphinx-based documentation support tool/formatter will be tracked now by issue #166.
Formatter steps.doc (or: steps, steps.usage) should satisfy the basic need for test writers, etc. (until a better solution arrives).

from behave.