[More Detail] [Collapse All]
Feature: Create implementation blueprints for developers


Sbuilder tool allows extracting specification snippets to a markdown
formatted files.

Markdown file location is defined in 'generate' section in
sbuilder.yaml using 'output' property. Specification snippets to
include in the output are listed under 'inputs' property.

Developer Blueprints are generated using mustache template
rendering. This makes it possible to include "normal" text generated
model snippets to the output.

TLA+ model generation in sbuilder is based on this same technique,
and this extension point can be used to replace the default
generation process.
features/080-blueprints/generate-blueprint.feature
- Background: Configure output generation process
link

Define two output files 'web/implementation-unit-1.md' and
'web/implementation-unit-2.md'.

File 'web/implementation-unit-1.md': 
- head line 'Heading for specification_snippet content'
- contents of the 'specification_snippet.txt' file

File 'web/implementation-unit-2.md' outputs: 
- defined types in the model
- domain in setup
features/080-blueprints/generate-blueprint.feature:20
Given I use a fixture named "fixture-resolver"
And YAML configuration file `cnf/sbuilder.yaml`
#
# 'setups' section defines a setup 'demo' 

setups:
- setupDirectory: default
- setupDirectory: test
And YAML configuration file `cnf/sbuilder.yaml`
#
# 'generate' section defines a setup 'output' to file
# <gen_dir>/<setup>/web/implementation-unit-1.md

generate:

   - output: web/implementation-unit-1.md
     inputs: 

       - desc: Heading for specification_snippet content
         modelData: none
         template: markdown-header.mustache
         templateParameters:
            include: specification_snippet.txt

   - output: web/implementation-unit-2.md
     inputs: 

       - desc: Heading for specification_snippet content
         modelData: none
         template: markdown-header.mustache
         templateParameters:
            include: specification_snippet.txt

       - desc: Type definitions
         modelData: definitions
         template: markdown-header.mustache
         templateParameters:
              include: definition_types.mustache

       - desc: Domain definitions
         modelData: domains
         template: markdown-header.mustache
         templateParameters:
              include: setup/domains_run.mustache
And a file named "src/specification_snippet.txt" with:
{{!  
     Specification snippet in mustache template format.
     NOT outputted => This comment is NOT in TLA+ model.
}}
(* This is TLA+ comment *)
- Scenario: Includes manual specification snippets
link

Generation:

- creates output file 'gen/default/web/implementation-unit-1.md'
  with

  -- with headline from configuration

  -- result of mustache rendering of 'specification_snippet.txt'
     (without mustache template comments)
features/080-blueprints/generate-blueprint.feature:100
Given I successfully run `sbuilder.rb generate default`
Then the following files should exist:
gen/default/web/implementation-unit-1.md
gen/default/web/implementation-unit-2.md
Then a file named "gen/default/web/implementation-unit-1.md" should exist
And the file named "gen/default/web/implementation-unit-1.md" should match /##\s*.*Heading for specification_snippet content/
And the file named "gen/default/web/implementation-unit-1.md" should contain "This is TLA+ comment"
And the file named "gen/default/web/implementation-unit-1.md" should not contain "is NOT in TLA+ model"
And the file named "src/specification_snippet.txt" should contain "is NOT in TLA+ model"
- Scenario: Includes snippets from specifiction generation
link
features/080-blueprints/generate-blueprint.feature:125
Given I successfully run `sbuilder.rb generate test`
Then the following files should exist:
gen/test/web/implementation-unit-1.md
gen/test/web/implementation-unit-2.md
And the file named "gen/test/web/implementation-unit-2.md" should match /##\s*.*Heading for specification_snippet content/
And the file named "gen/test/web/implementation-unit-2.md" should contain "Type definitions"
And the file named "gen/test/web/implementation-unit-2.md" should contain "Domain definitions"