Framstag / semtrail

SemTrail is a small project to generate a simple WebPage for a semantic graph defined by a small DSL file
Apache License 2.0
1 stars 0 forks source link
requirements-management

About "SemTrail"

About

SemTrail was created because I had the need to document and structure a medium number interconnected requirements. Customer requirements and facts lead over a number of indirections to a concrete architecture.

It uses a LISP/Clojure-like DSL for describing requirements, facts, conclusions and similar using typed nodes. Interconnections are defined via edge that also have a type. This builds a semantic graph.

From the description file an internal model is build.

It uses Thymeleaf for generating the resulting web pages base don the passed internal model.

Current status

The current status is "it starts to work for me but I'll likely add some further small enhancements".

Be invited!

If you are interested, participate.

The name...

The project visualizes a trail from customer requirements to conceptual solutions and finally to concrete technological decisions. In principle, it is a semantic graph. Where each node is a requirement, a concept or a technical solution and each edge represents a deduction, a decision, a possible alternative or similar.

The similarity between "SemTrail" and "Chemtrail" was realized and found to be funny. Also, some architecture claims to have its origin in a path of concrete, well thought of decisions - but nobody never has seen them, neither are they documented.

How to use

Simply call it using

SemTrail <description file>.semtrail <template directory> <target directory>

There are currently some quirks in the command line handling and resulting processing. So expect errors if you do not follow the expected syntax.

Reports

The current version using the default templates generates the following navigable pages:

Page Template Content
All index.html Tabular representation of all defined nodes
All (Map) image.html Network-lke visualisation of all nodes and their connecting edges
\<Node type> index.html For each node type a tabular representation of all node of this type
Starter index.html A list of all nodes that "start" a directed graph
Leaves index.html A list of all nodes that have only incoming edges
By #causes index.html A list of all nodes sorted by the number of incoming edges
By #consequences index.html A list of all nodes sorted by the number of outgoing edges
By #connected index.html A list of all nodes sorted by the sum of incoming and outgoing edges
Orphans index.html A list of nodes that have neither incoming nor outgoing edges
Missing Documentation index.html A list of nodes that have no documentation

Besides above pages a page for each node is generated using the node.html template.

The following additional template files are used for reusing and sharing content over all generated pages and should be referenced from above pages:

File Content
footer.html Common footer of each page
header.html Common header of each page
navigation.html Common navigation component
standard.css Common style sheet

Data passed to the templates

The template gets passed the following objects, depending on its meaning:

Object Type Passed to Description
model Model Always The data parsed from the semtrail file
config Config Always Additional configuration data
node Node Detail page of a node The current node
nodes List\<Node> List of nodes The (possibly filtered) list of nodes to display

The Model type

The Model class has the following attributes:

Attribute Type Description
nodeTypes Map\<String,NodeType> map of node type names to node types
edgeTypes Map\<String,EdgeType> map of edge type names to edge types
nodeMap Map\<String,Node> Mapping from node name to Node type instance

The Config type

The Config class has the following attributes:

Attribute Type Description
pages List\<Page> List of pages

The Page type

The Page class has the following attributes:

Attribute Type Description
page Path path of the generated page
label String label for the generated page

The NodeType type

Attribute Type Description
type String The type name of the node type
name String The descriptive name of the node type
color String The color for the node

The EdgeType type

Attribute Type Description
type String The type name of the edge type
name String The descriptive name of the edge type
color String The color for the edge

The Node type

Attribute Type Description
name String The name of the node
type String The name of the node type
doc String A documentation
fromNodes Map\<String,Edge> Map from edge name to Edge type instance for all incoming edges
toNodes Map\<String,Edge> Map from edge name to Edge type instance for all outgoing edges

The Edge type

Attribute Type Description
type String The type name
from Node The from Node
to Node The to Node
doc String A documentation

Syntax of *.semtrail files

TODO

Simple Docker Image for hosting the generation result

The repository contains a simple Dockerfile as boiler plate example for hosting the generated static web pages using nginx. This is not a production ready example, only a simple show cases for tests. Make sure that you host static content with the base images you trust.

Build the docker container:

./build_docker.sh

This copies the relevant files in to a maven-based base Image (maven:latest from docker.io), starts a maven build and generate the static pages for Semtrail.semtrail.

Afterwards it creates a nginx based image (framstag/semtrail:latest) with the above generated static content to serve.

Running the image:

./run_docker.sh

This runs the nginx in the resulting Docker image under localhost:8080