Generate documentation from stories
hitchstory YAML stories are designed to be readable, but also terse and easy to maintain.
Where terseness and ease of maintenance trumps readability, the former take precedence. YAML stories are not intended to be a replacement for stakeholder documentation in and of themselves.
YAML stories are designed, however, to be used to generate documentation for use by stakeholders.
The example shown below demonstrates how a story can be transformed into markdown via jinja2. This markdown can then be used to generate HTML with a static site generator.
example.story:
Login:
about: Simple log in.
with:
username: AzureDiamond
password: hunter2
given:
url: /loginurl
steps:
- Fill form:
username: (( username ))
password: (( password ))
- Click: login
Log in on another url:
about: Alternate log in URL.
based on: login
given:
url: /alternativeloginurl
Log in as president:
about: For stories that involve Trump.
based on: login
with:
username: DonaldTrump
password: iamsosmrt
engine.py:
from hitchstory import BaseEngine, GivenDefinition, GivenProperty, about
from strictyaml import Map, Int, Str, Optional
class Engine(BaseEngine):
given_definition = GivenDefinition(
url=GivenProperty(schema=Str(), document="Load: {{ url }}"),
)
def set_up(self):
print("visit {0}".format(self.given['url']))
@about((
"{% for name, value in textboxes.items() %}\n"
"- Enter text '{{ value }}' in {{ name }}.\n"
"{%- endfor %}\n"
))
def fill_form(self, **textboxes):
for name, text in sorted(textboxes.items()):
print("with {0}".format(name))
print("enter {0}".format(text))
@about("* Click on {{ item }}")
def click(self, item):
print("clicked on {0}".format(item))
from hitchstory import StoryCollection
from pathquery import pathquery
from engine import Engine
from path import Path
from jinja2 import Template
Generate from story:
print(
Template(Path("documentation.jinja2").text()).render(
story_list=StoryCollection(
pathquery(".").ext("story"), Engine()
).non_variations().ordered_by_file()
)
)
Will output:
Login
-----
Simple log in.
Load: /loginurl
- Enter text 'AzureDiamond' in username.
- Enter text 'hunter2' in password.
* Click on login
Log in on another url
---------------------
Alternate log in URL.
Load: /alternativeloginurl
- Enter text 'AzureDiamond' in username.
- Enter text 'hunter2' in password.
* Click on login
Log in as president
-------------------
For stories that involve Trump.
Load: /loginurl
- Enter text 'DonaldTrump' in username.
- Enter text 'iamsosmrt' in password.
* Click on login
Executable specification
Page automatically generated from documentation.story.