Step documentation

<- Back to home

behave-toolkit can generate a Sphinx-ready technical reference from a Behave project. This is aimed at the consumer suite you are testing, not at the toolkit repository itself.

You can ignore this feature until your step library is large enough that a searchable reference site would genuinely help the team.

After a plain pip install behave-toolkit, you can:

1. use the Python API in features/environment.py for lifecycle/config wiring

2. call configure_parsers(CONFIG_PATH) at import time if your config defines custom Behave types

3. run behave-toolkit-docs to generate documentation sources

4. run python -m sphinx ... to build the final HTML site

Generate the sources

behave-toolkit-docs --features-dir features --output-dir docs/behave-toolkit

If you prefer to drive the generator from Python, the public API is:

from behave_toolkit import generate_step_docs

result = generate_step_docs(
    "features",
    "docs/behave-toolkit",
    site_title="QA Step Catalog",
)
print(result.step_count, result.type_count)

generate_step_docs(...) returns a DocumentationResult with the output path and the number of generated step and type pages.

The generated output includes:

• a Sphinx/MyST scaffold with conf.py

• grouped keyword pages (Given, When, Then, Generic)

• one page per step definition

• one page per custom parse type

• links from typed parameters back to their type pages

• feature-file examples attached to matching steps

• enum values when a converter exposes an enum return annotation

• structured Google-style Args, Returns, and Raises sections when present

Build the final HTML site

python -m sphinx -b html docs/behave-toolkit docs/_build/behave-toolkit

Typical end-to-end flow in a consumer project:

pip install behave-toolkit
behave-toolkit-docs --features-dir features --output-dir docs/behave-toolkit
python -m sphinx -b html docs/behave-toolkit docs/_build/behave-toolkit

Recommended type-registration pattern

Custom parse types should still be configured at import time, before step loading. The recommended pattern is:

1. define converters or enums in a dedicated support module

2. declare them in behave-toolkit.yaml under parsers:

3. call configure_parsers(CONFIG_PATH) from features/environment.py

4. import the resulting Python types in your step modules if you want annotations

This keeps both Behave itself and the generated documentation aligned.

Documentation-friendly step design

The generator works best when steps are:

• annotated with meaningful parameter types

• documented with concise summaries in the first paragraph

• backed by real .feature examples in the suite

• using Google-style docstrings when you want richer parameter/return/raise sections in the output

Tip

Even if your step library grows large, generated reference pages stay readable when the first paragraph of each docstring is a clean one-line summary.