Merge pull request #16 from kieler/cfr/local-doc-example

Docs: Add a local documentation example
kieler · Sep 16, 2021 · 92ad4e3 · 92ad4e3
2 parents 0f08fc2 + 1f08ef6
commit 92ad4e3
Show file tree

Hide file tree

Showing 4 changed files with 193 additions and 0 deletions.
diff --git a/examples/local-documentation/README.md b/examples/local-documentation/README.md
@@ -0,0 +1,24 @@
+# Using the CLI for Local Documentation
+
+This example highlights how the CLI can be used to embed a diagram visualization in local web-based
+documentation.
+
+> The key ingredients are `iframe` elements and the `klighd serve` command.
+
+`Serve` starts the web server, but does not open a diagram view. Instead, `iframe` elements embed
+diagram views into the documentation by pointing to the started web server and provide paths to the
+files that should be visualized.
+
+An example for a documentation that relies on the
+[KIELER language server](https://rtsys.informatik.uni-kiel.de/~kieler/files/release_sccharts_1.2.0/ls)
+can be found in the `index.html` file.
+
+Steps required to try the example yourself:
+
+1. Download the content of this (`local-documentation`) folder or clone this repo.
+2. Download the latest version of the CLI [here](https://github.com/kieler/klighd-vscode/releases)
+   if not done already.
+3. In the `index.html` file, modify the absolute paths in the `iframe` elements to match your local
+   file structure. (Relative paths do not work)
+4. Run `klighd serve -p 8000`.
+5. Open the `index.html` file in a browser and enjoy!
diff --git a/examples/local-documentation/first-embed.elkt b/examples/local-documentation/first-embed.elkt
@@ -0,0 +1,24 @@
+node a {
+    layout [size: 70, 20]
+    label "Node A"
+}
+node b {
+    layout [size: 70, 20]
+    label "Node B"
+}
+node c {
+    layout [size: 70, 20]
+    label "Node C"
+}
+
+edge a -> b {
+    label "Transition 1"
+}
+
+edge b -> a {
+    label "Transition 2"
+}
+
+edge b -> c {
+    label "Transition 3"
+}
diff --git a/examples/local-documentation/index.html b/examples/local-documentation/index.html
@@ -0,0 +1,117 @@
+<!--
+ KIELER - Kiel Integrated Environment for Layout Eclipse RichClient
+
+ http://rtsys.informatik.uni-kiel.de/kieler
+
+ Copyright 2021 by
+ + Kiel University
+   + Department of Computer Science
+     + Real-Time and Embedded Systems Group
+
+ This program and the accompanying materials are made available under the
+ terms of the Eclipse Public License 2.0 which is available at
+ http://www.eclipse.org/legal/epl-2.0.
+
+ SPDX-License-Identifier: EPL-2.0
+-->
+
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf-8" />
+        <title>Viva La Lorem Ipsum</title>
+        <style>
+            body {
+                display: flex;
+                flex-direction: column;
+                align-items: center;
+                margin: 24px;
+            }
+            h1 {
+                text-align: center;
+                margin: 0 0 16px 0;
+            }
+            main {
+                max-width: 600px;
+            }
+            .diagram-view {
+                border: 1px solid black;
+                width: 100%;
+                height: 400px;
+            }
+        </style>
+    </head>
+    <body>
+        <header><h1>Viva La Lorem Ipsum</h1></header>
+        <main>
+            <p>
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi venenatis ex justo,
+                vel dapibus ex aliquam eget. Nullam eleifend orci a mauris elementum rutrum. Nullam
+                ultrices dictum lectus, nec sollicitudin augue dapibus ac. Vestibulum tellus libero,
+                fermentum ac velit vitae, cursus scelerisque nunc. Morbi auctor consequat rhoncus.
+                Nullam efficitur quam eget ultricies rhoncus. Nullam finibus elit tristique,
+                suscipit leo bibendum, iaculis lectus. Aliquam erat volutpat. Ut ac lectus nec nisl
+                pellentesque malesuada.
+            </p>
+            <p>
+                Donec nulla diam, molestie vestibulum malesuada quis, lobortis porta felis.
+                Vestibulum faucibus, enim sed tincidunt sollicitudin, justo ante ornare turpis,
+                vitae sagittis purus tellus in mauris. Nullam luctus hendrerit risus, nec auctor
+                quam vehicula eu. Phasellus vel ultricies magna, nec convallis dui. Maecenas in
+                turpis a nisi vestibulum vulputate. Maecenas sollicitudin et metus quis suscipit.
+                Donec mollis fringilla eros, ut aliquam diam consequat sed. Morbi dui diam, mollis
+                ac varius vel, aliquam vitae mauris. Phasellus sed dictum eros. Phasellus ac
+                facilisis turpis, non mollis enim. Vestibulum vitae auctor mauris. Maecenas et nibh
+                faucibus urna euismod venenatis.
+            </p>
+            <!-- The source path provided to "src" has to be modified! -->
+            <iframe
+                src="http://127.0.0.1:8000/?source=file:///home/cf/Documents/bachelor/klighd-web/examples/local-documentation/first-embed.elkt"
+                frameborder="0"
+                class="diagram-view"
+            ></iframe>
+            <p>
+                Nulla sagittis sollicitudin justo, in auctor ligula scelerisque non. Nunc commodo
+                nunc vitae mauris porttitor tincidunt. Fusce vestibulum mauris bibendum iaculis
+                elementum. Praesent ac mauris vel diam venenatis imperdiet sed ut eros. Nullam
+                dignissim tellus in diam auctor, ac vulputate lectus facilisis. Nunc cursus, ante ut
+                dictum luctus, augue nisl tincidunt magna, eget euismod ligula mi a diam. Vivamus
+                nec diam auctor, ullamcorper orci id, ultrices arcu. Vivamus accumsan pretium
+                maximus. Phasellus volutpat nulla et elit finibus, a volutpat dolor consectetur. Nam
+                pharetra ante eros, non varius dui eleifend non.
+            </p>
+            <p>
+                Vestibulum commodo ullamcorper lacus. Fusce vel ipsum eu sapien malesuada semper.
+                Donec at placerat dolor, a semper metus. Cras ligula ex, eleifend vel sem id,
+                pulvinar gravida nulla. Maecenas eget nunc elementum, sodales dolor quis, sodales
+                mauris. Sed nec ipsum magna. Duis sagittis ex erat, id rhoncus nisl rutrum non.
+                Phasellus imperdiet nisi eu convallis porttitor. Phasellus elementum ac ex ut
+                lobortis. Mauris ultrices mattis lorem, in lacinia orci pellentesque ac.
+                Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
+                egestas. Cras lacinia, nisl at scelerisque tincidunt, dolor libero mattis tellus,
+                ornare ultricies mauris justo sit amet leo. Nulla ac neque pharetra, varius nunc at,
+                elementum augue. Maecenas nisl nibh, scelerisque vel facilisis non, venenatis
+                laoreet magna.
+            </p>
+            <!-- The source path provided to "src" has to be modified! -->
+            <iframe
+                src="http://127.0.0.1:8000/?source=file:///home/cf/Documents/bachelor/klighd-web/examples/local-documentation/second-embed.sctx"
+                frameborder="0"
+                class="diagram-view"
+            ></iframe>
+            <p>
+                Ut eget enim elit. Proin scelerisque est a felis blandit, at venenatis leo rhoncus.
+                Nam suscipit augue ut mi lobortis cursus. Sed nec porttitor nisl. Aliquam erat
+                volutpat. Nullam convallis a eros sit amet volutpat. Nunc nunc dui, semper vitae
+                facilisis in, placerat nec enim. In pellentesque nunc non sapien facilisis, nec
+                elementum leo iaculis. Etiam sollicitudin arcu et ligula tempus vehicula. Nunc
+                porttitor bibendum tellus, nec fringilla neque molestie id. Phasellus bibendum lacus
+                commodo velit commodo accumsan vel aliquet libero. Praesent metus quam, euismod eget
+                pulvinar eget, bibendum eu est. Maecenas ullamcorper id quam ac eleifend. Nunc a
+                massa accumsan, tempus nisl eget, vehicula quam. Integer et elit luctus erat
+                sollicitudin faucibus. Quisque tristique felis at lacus efficitur, vitae venenatis
+                neque mattis.
+            </p>
+        </main>
+    </body>
+</html>
diff --git a/examples/local-documentation/second-embed.sctx b/examples/local-documentation/second-embed.sctx
@@ -0,0 +1,28 @@
+scchart ABRO {
+	input bool A, B, R
+	output bool O
+
+	initial state ABO {
+		entry do O = false
+
+		initial state WaitAB {
+			region handleA {
+				initial state wA
+				if A go to dA
+
+				final state dA
+			}
+
+			region handleB {
+				initial state wB
+				if B go to dB
+
+				final state dB
+			}
+		}
+		do O = true join to done
+
+		state done
+	}
+	if R abort to ABO
+}