sysl-catalog

README

sysl-catalog

A markdown/html + Diagram generator for sysl specifications

Installation

go get -u -v github.com/anz-bank/sysl-catalog

How to use

1. Set up environment export SYSL_PLANTUML=http://www.plantuml.com/plantuml

2. Run

sysl-catalog -o <output directory> <input.sysl>

• You can optionally specify the --type=html if you want to generate html instead of markdown, which is useful for use with github pages, which you can see a demo of with this repo here

1. That's it (basically!)

   This will generate markdown with integration diagrams + sequence diagrams + data model diagrams as seen in demo/markdown/README.md or see html generation at demo/html/index.html.

Server Mode

sysl-catalog comes with a serve mode which will serve on port :6900 by default

sysl-catalog --serve <input.sysl>

This will start a server and filewatchers to watch the input file and its directories recursively, and any changes will automatically show:

Requirements

In demo/markdown/README.md we have an example with a couple of interesting parts:

1. @package attribute must be specified:

• This will create a markdown page for ApplicationPackage as seen in demo/markdown/ApplicationPackage/README.md. Currently the package name is not inferred from the application name (MobileApp), so this needs to be added (ApplicationPackage).

MobileApp:
    @package = "ApplicationPackage"
    Login(input <: Server.Request):
        Server <- Authenticate
        return ok <: MegaDatabase.Empty

1. Application names might need to be prefixed to parameter types if the type is defined in another application, since defined parameters are under scope of the application it is defined in:

MobileApp:
    @package = "ApplicationPackage"
+    Login(input <: Server.Request):
-    Login(input <: Request):
        Server <- Authenticate
        return ok <: MegaDatabase.Empty

1. Add ~ignore to applications/projects that are to be ignored in the markdown creation

ThisAppShouldntShow[~ignore]:
    NotMySystem:
        ...
# Or ignore only specific endpoints
ThisAppShouldShow[~ignore]:
    NotMySystem[~ignore]:
        ...

CLI options

Output default Markdown

sysl-catalog -o=docs/ filename.sysl

Output default HTML

sysl-catalog -o=docs/ --type=html filename.sysl

Run with custom templates

• With this the first template will be executed first, then the second sysl-catalog --templates=<fileName.tmpl>,<filename.tmpl> filename.sysl

Run in server mode

sysl-catalog --serve filename.sysl

Generate Redoc files

sysl-catalog --redoc filename.sysl This generates a Redoc page that serves the original .json or .yaml OpenAPI spec on Github. Currently only supports spec files located in the same repo, and must be run in a git repo (so that the remote url can be retrieved using git).

Run in server mode without css/rendered images

• good for rendering raw markdown

sysl-catalog --serve --noCSS filename.sysl

Run server with custom template

sysl-catalog --serve --templates=<fileName.tmpl>,<filename.tmpl> filename.sysl

• See templates/ for custom template examples

Screenshots

project_view

package_view