Configuration explorer cleanup

OPAL/ProjectDependencies.mmd

@@ -27,6 +27,8 @@ flowchart BT
     bp[BugPicker\n bp]
     hermes[Hermes\n hermes]
 
+    ce[ConfigurationExplorer \n ce]
+
     style common fill:#9cbecc,color:black
     style framework fill:#c0ffc0
     style bp fill:#ffd7cf
@@ -68,4 +70,10 @@ flowchart BT
 
     demos --> framework
     bp --> framework
-    hermes --> framework
+    hermes --> framework
+
+    ce --> br
+    ce --> apk
+    ce --> demos
+    ce --> hermes
+    ce --> bp

TOOLS/ce/build.sbt

@@ -0,0 +1 @@
+// build settings reside in the opal root build.sbt file

TOOLS/ce/readme.md

@@ -0,0 +1,131 @@
+# Configuration explorer documentation
+## How to document your configs
+The configuration explorer uses a custom parser to parse flags into a browsable documentation
+This makes every element of your config documentable. 
+This guide is about to teach you how to utilize these flags to create a comprehensible documentation
+
+### How do I create a browsable configuration?
+1. Start up your sbt shell
+2. run the doc command
+3. Open the generated commentedconfigs.html in your source directory
+
+### Where can I add my documentation?
+You can add your documentation in the lines before an element, or directly behind the element within the same line.
+
+```
+    // You can either add your comment to the element here
+    Value = "one"  //Or you can also add your comment here
+
+    // However, you cannot add your comment here 
+```
+
+Also keep in mind that HOCON allows for multiple values within one line. 
+In this case, the comment will be associated with its closest neighbor that fullfills the criteria:
+
+```
+    Object = {Key = "Value", AnotherKey = "SecondValue"} // This comment will be associated with Object, since its closing bracket is closest
+```
+
+Sub-values need to be placed in its own lines in order to be documented.
+
+### Usage of flags
+
+The configuration explorer allows for different flags to be utilized for different elements of the documentation.
+Each flag will be interpreted differently and be represented in a different way after exporting.
+
+The flags can be grouped in two groups, by the point in time where they are visible when the documentation is exported.
+
+#### @label
+@label documents the label of the object.
+It will be shown in the documentation as the name of the object and will be visible even when the object is collapsed.
+If the configuration element is part of an object, the label will be automatically set as its identifier within the object.
+This is overridable by manually setting the @label flag within its documentation.
+
+```
+    {
+        key = "value" // The label property will be set to "key" automatically.
+
+        //@label Custom label
+        another_key = "value" // The label property is now overridden to "Custom label"
+    }
+```
+
+#### @brief
+@brief shows a brief description of the element for easier comprehension without the need for expanding the element.
+For optimal formatting, try to keep the length of the text behind this flag below 50 characters.
+
+#### @description
+@description will set the description of the configuration element when the element is expanded.
+Usage of the flag is optional, as unflagged content will be added to the description area too.
+
+```
+    {
+        // @description You can use this flag to add this text to the elements description.
+        // However, without any flags, the text will be added to the description too.
+        key = "value"
+    }
+```
+
+#### @type
+@type can be used to indicate the type of a value that will be used.
+
+##### Subclass type
+The subclass type is one of two special types currently implemented into Configuration Explorer
+When tagged with a subclass type, configuration explorer will search for all subclasses of a given root class.
+
+##### Enum type
+The enum type is the second of the special types in Configuration Explorer. Use it if you have a finite amount of allowed values that you all want to list in the constraints. 
+
+##### Other types
+You can pick a type that you want to indicate, which logical restraints are, but they will be treated as-is and not be refined further. 
+
+#### @constraint
+Use @constraint to define which values are allowed and which are not. 
+If there are multiple constraints, use a new line for each constraint using the flag "@constraint" at the beginnning of each line.
+
+There are currently two types implemented where you use a special style to list constraints:
+##### Subclass type
+If your type is "subclass", then list exactly one constraint. The constraint must be the class where all allowed classes inherit from. 
+Configuration Explorer will fetch all valid Subclasses of the listed class and list these in the documentation. You may specify a different value in the value field when generating the documentation.
+
+Example:
+```
+    {
+        // @description Configuration Explorer will list all subclasses of ConfigNode as allowed values. (Which are ConfigObject, ConfigList, ConfigEntry)
+        // @type subclass
+        // @constraint ConfigNode
+        value = ConfigObject 
+    }
+```
+
+##### Enum type
+Create one line with the constraint flag for every allowed value that you want to list.
+
+Example:
+
+```
+    {
+        // @description Add one row for each allowed value
+        // @type enum
+        // @constraint two
+        // @constraint three
+        // @constraint five
+        // @constraint seven
+        primeNumberBelowTen = 3
+    }
+```
+
+#### Other types
+The constraints for other types will be passed as-is and can be in a free text.
+
+Example:
+
+```
+    {
+        // @type int
+        // @constraint Values must be within 0 and 100
+        // @constraint Values must be even
+        key = 2
+    }
+```
+

TOOLS/ce/src/main/resources/ce.conf

@@ -0,0 +1,61 @@
+// @brief Configuration for the config explorer
+// @description Settings under this hierarchy control the configuration explorer options
+
+{
+    org.opalj.ce {
+        // @brief Used filenames for configurations
+        // @description This setting contains a list of filenames that are in use for configuration files in this project
+        // reference.conf, application.conf are default filenames defined by the maker of typesafe configuration
+        // @type String
+        configurationFilenames = ["ce.conf","reference.conf","application.conf", "hermes.conf","CommandLineProject.conf","LibraryProject.conf","NoTransformations.conf"]
+
+        // @brief Toggle for replacing classes in the configuration documentation
+        // @description You can use this option to activate / deactivate the replacement of subclass type configuration entries
+        // When activated, ce will list all implemented subclasses able to replace a class type value
+        // @type Boolean
+        replaceSubclasses = true
+
+        // @label HTML Settings
+        // @brief These settings store the information for the HTML export
+        html = {
+            // @brief Path to the HTMLTemplate
+            // @description This setting contains a relative path from the projects root to the file that stores the HTML Stylesheet and the JavaScript components
+            // @type String
+            // @constraint must be a path to an existing html file in Linux syntax (use / instead of \)
+            template = "/TOOLS/ce/src/main/resources/template.html"
+
+            // @brief Defines the headline of a config Node
+            // @description This sets the syntax for the headline of a config node.
+            // $label will be replaced with the label of the ConfigNode
+            // $brief will be replaced with the brief description of the ConfigNode
+            // This does not render correctly on the documentation due to it being an HTML expression
+            // @type String
+            // @constraint Must be a valid closed HTML expression
+            headline = "<h3 class=\"header\"> $label <span class=\"preview\">- $brief </span><span class=\"expandBox\">Show</span></h3>"
+
+            // @brief defines syntax of the content bracket
+            // @description This setting sets the syntax of the content brackets
+            // $content is a placeholder that will be replaced with the further content of the config node
+            // This does not render correctly on the documentation due to it being an HTML expression
+            // @type String
+            // @constraint Must be a valid closed HTML expression
+            // @constraint Must contain the placeholder $content
+            content = "<div class=\"content\"> $content </div>"
+
+            // @brief Defines the export path of the commented commentedconfigs
+            // @type String
+            // @constraint must be a file name
+            export = "/commentedconfigs.html"
+
+            // @brief Defines if the keys in the export should be sorted alphabetically
+            // @type boolean
+            sort_alphabetically = false
+
+            // @brief Defines how long the fallback preview of the brief description can be
+            // @description This value defines, how long the preview in the brief window can be, if there is not explicit brief description available.
+            // The number is the amount of characters displayed.
+            // @type Integer
+            maximum_headline_preview_length = 70
+        }
+    }
+}

TOOLS/ce/src/main/resources/template.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>OPAL Config Documentation</title>
+    <style>
+        body {
+            font-family: sans-serif;
+            padding: 1em;
+        }
+
+        hr {
+            margin-top : 2em;
+            margin-bottom: 2em;
+            color: #DCDCDE;
+        }
+        .content {
+            padding: 1em;
+            border: 0.1em solid #DCDCDE;
+            border-radius: 0.5em;
+            margin-left: 2em;
+            display: none;
+        }
+
+        .header {
+            cursor: pointer;
+            color: #28272D;
+            background-color: #FBFAFD;
+        }
+
+        .preview {
+            font-weight: normal;
+            font-size: 0.65em;
+            color: #626168;
+        }
+
+        .expandBox {
+            float: right;
+            color: #626168;
+            font-size: 0.5em;
+            padding: 0.4em;
+            border: 0.1em solid #DCDCDE;
+            border-radius: 0.25em;
+            border-collapse: collapse;
+        }
+    </style>
+</head>
+<body>
+
+$body
+
+<script>
+    document.querySelectorAll('.header').forEach(header => {
+        header.addEventListener('click', () => {
+            const content = header.nextElementSibling;
+            const expandBox = header.querySelector('.expandBox');
+
+            if (content.style.display === 'none' || content.style.display === '') {
+                content.style.display = 'block';
+                expandBox.textContent = 'Hide';
+            } else {
+                content.style.display = 'none';
+                expandBox.textContent = 'Show';
+            }
+        });
+    });
+</script>
+
+</body>
+</html>