Merge pull request #14 from danyill/issue-13-docs

Add initial docs, closes #13

Author: danyill

.gitignore

@@ -15,6 +15,7 @@
 
 # IDE
 /.idea
+*.iml
 
 # failed screenshots
 test/screenshots/failed/

README.adoc

@@ -1,270 +1,29 @@
-= OpenSCD Plugin: {plugin-name} Editor
-:plugin-name: Supervision
+= OpenSCD Plugin: Supervision
+:plugin-name: oscd-supervision
 :sectnums:
 :sectlinks:
 :toc: macro
 :imagesdir: docs/media
 :icons: font
 :experimental:
-:uri-action-translate-ci-bundle: https://jakobvogelsang.github.io/oscd-action-translate/oscd-action-translate.js
-:uri-openscd-core: https://github.com/openscd/open-scd-core#readme
-:uri-openscd: https://github.com/openscd
-:uri-openscd-app: https://openscd.github.io
-:uri-openscd-core-app: https://openscd.github.io/open-scd/
-:uri-openscd-core-plugin: pass:v[https://openscd.github.io/open-scd/?plugins=%7B%22menu%22:%5B%7B%22name%22:%22Open%20File%22,%22translations%22:%7B%22de%22:%22Datei%20%C3%B6ffnen%22%7D,%22icon%22:%22folder_open%22,%22active%22:true,%22src%22:%22https://openscd.github.io/oscd-open/oscd-open.js%22%7D,%7B%22name%22:%22Save%20File%22,%22translations%22:%7B%22de%22:%22Datei%20speichern%22%7D,%22icon%22:%22save%22,%22active%22:true,%22src%22:%22https://openscd.github.io/oscd-save/oscd-save.js%22%7D%5D,%22editor%22:%5B%7B%22name%22:%22Supervision%22,%22translations%22:%7B%22de%22:%22%C3%9Cberwachung%22,%22pt%22:%22Supervis%C3%A3o%22%7D,%22icon%22:%22ecg%22,%22active%22:true,%22src%22:%22https://danyill.github.io/oscd-supervision/oscd-supervision.js%22%7D%5D%7D]
-// TIP:
-// the above URI is done by taking the plugins object from demo.html (without strings) and updating to the correct {uri-ci-bundle} value and then in the browser calling:
-// console.log(`https://openscd.github.io/open-scd/?plugins=${encodeURI(JSON.stringify(plugins))}`)
-// then substitute the value within the pass:v[<url>]
 :uri-openwc: https://github.com/open-wc/open-wc
-:uri-plugin: https://github.com/danyill/oscd-supervision
-:uri-ci-bundle: https://danyill.github.io/oscd-supervision/oscd-supervision.js
-:uri-material-icons: https://fonts.google.com/icons
-:uri-openscd-core-plugin-demo: https://danyill.github.io/oscd-supervision/index.deploy.html
-
+:uri-docs: https://danyill.github.io/tpnz-openscd-docs
+:uri-openscd-core-plugin-demo: https://danyill.github.io/{plugin-name}/index.deploy.html
 // badges
-image:https://github.com/danyill/oscd-subscriber-later-binding/actions/workflows/test.yml/badge.svg[title='Build Status']
+image:https://github.com/danyill/oscd-supervision/actions/workflows/test.yml/badge.svg[title='Build Status']
 image:https://img.shields.io/badge/built%20with-open--wc-blue.svg[link={uri-openwc},title='Built with open-wc recommendations']
-image:https://img.shields.io/badge/LF%20Energy%20Slack-%20%23OpenSCD%20chat-purple?logo=slack&color=2aa198&labelColor=6c71c4[link=https://lfenergy.slack.com/archives/C03LH7EUP34,title='Slack LF Energy']
+image:https://img.shields.io/badge/Zulip%20-%20%23OpenSCD%20chat-purple?logo=zulip&color=2aa198&labelColor=6c71c4[link=https://openscd.zulipchat.com/]
 
 toc::[]
 
 == What is this?
 
 This plugin is intended to allow a user to add, remove and configure IEC 61850 GOOSE and SMV supervisions:
 
-* This is a plugin for {uri-openscd-core}[open-scd-core], the core
-editor engine for {uri-openscd}[OpenSCD].
-
-* This plugin is a web component and follows the
-{uri-openwc}[open-wc] recommendations.
-
-* This plugin uses the link:LICENSE[Apache License] and is intended for you to use, study, share and improve.
-
-{uri-openscd-core-plugin-demo}[Try it out online]!
-
-.Supervision Editor Plugin
-image::../../test/screenshots/baseline/LGOS changes supervisions can delete a used supervision-Chromium.png[width=800,link=../../test/screenshots/baseline/LGOS changes supervisions can delete a used supervision-Chromium.png]
+This is a plugin for OpenSCD core, the core editor engine for OpenSCD.
 
 Feel free to log issues to request fixes, improvements or new features.
 
-=== Features
-
-* Supports GOOSE and SMV
-* Will instantiate supervisions if possible (if `valImport=true` and `valKind=RO` or `valKind=Conf` on the first LGOS/LSVS instance or the datatype)
-* Allows removals of supervision elements
-
-== How to use?
-
-=== Online Using the Latest open-scd-core
-
-==== Using a URL
-
-Open SCD core allows plugins to be loaded from a URL.
-
-You can click on {uri-openscd-core-plugin}[this link] to trial this plugin.
-
-In this view it is without theming and only presents this plugin along with the open and save plugins.
-
-==== Manually
-
-. The latest core is available at {uri-openscd-core-app}.
-
-. Go to menu:Menu[Add plugins...]
-
-. Select Cancel - this is an editor plugin.
-
-. Select OK to required a loaded document.
-
-. Choose a plugin name of '{plugin-name}'.
-
-. Choose a plugin icon of 'link'
-
-. Provide a plugin source URI of: {uri-ci-bundle}
-
-. Click OK on the summary, it should indicate the parameters previously entered.
-
-. Open a file and enjoy!
-
-=== Locally for testing
-
-. Clone this project:
-+
-[subs=+attributes]
-....
-$ git clone {uri-plugin}
-....
-
-. Install dependencies
-
-  $ npm i
-
-. Start up a demo server 
-
-  $ npm run start
-
-. Open in your browser locally at http://localhost:8000/demo/
-
-=== As part of the OpenSCD distribution
-
-TIP: OpenSCD is transitioning to use of `open-scd-core`, these instructions will require updating at the end of this transition.
-
-// TODO: Is this fixed yet?
-IMPORTANT: Currently the reactive update cycle in OpenSCD doesn't optimally support this plugin's behaviour -- it scrolls to the top of lists after a subscription is made or one of the window panes may go blank. This is a known issue and under investigation.
-
-. Open your OpenSCD distribution or use {uri-openscd-app}.
-
-. Create a custom extension by going to menu:menu[Extensions>Add Custom Extension].
-
-. Enter the name '{plugin-name}', select 'Editor tab' and enter {uri-ci-bundle} as the URL.
-+
-This is the URL of the bundle built by CI and is always the latest pre-release version of this plugin.
-+
-.OpenSCD Add Custom Extension Screen
-image::screenshot-add-extension.png[width=300]
-
-. Click on menu:Add[].
-
-. Until OpenSCD is fully transitioned to open-scd-core, a conversion plugin is also required to interface between the old and new APIs.
-
-. Create another custom extension by going to menu:menu[Extensions>Add Custom Extension].
-
-. Enter the name 'Action Translate', select 'Menu entry' and enter {uri-action-translate-ci-bundle} as the URL.
-+
-This is the URL of the bundle built by CI and is always the latest pre-release version of this plugin.
-
-. You should now be able to scroll across in the menu-bar and find a tab, "{plugin-name}"
-+
-TIP: If there are too many editor plugin, hold down shift and wheel-mouse up and down to scroll them easily.
-
-=== As part of your own distribution
-
-==== Within the current OpenSCD distribution
-
-. Within the current OpenSCD distribution, plugins are stored in the `public/js/plugins.js` folder. 
-Each plugin appears in the following form:
-+
-[source,js,subs=+attributes]
-----
-{
-    name: '{plugin-name}', // <.>
-    src: '{uri-ci-bundle}', //  <.>
-    icon: 'ecg', // <.>
-    default: true, // <.>
-    kind: 'editor', // <.>
-    requireDoc: true, // <.>
-    position: 'middle' // <.>
-  }
-----
-<.> Name of the plugin which appears in the editor menu at top of screen
-<.> URL which can be a local or remote resource. 
-For a local resource, begins without a forward slash, e.g. `plugins/oscd-supervision/dist/oscd-supervision.js`. 
-In this case what is shown is loading a plugin from the build process.
-<.> A material icon, see others at {uri-material-icons}[Material Symbols and Icons]
-<.> Whether the plugin is enabled by default or has to be enabled in the plugins menu
-<.> The type of plugin, either `menu` or `editor`. This is an `editor` plugin.
-<.> Whether a document must be loaded for this plugin to be available
-<.> A string, either `top`, `middle` or `bottom` to give a location in the menu. 
-Otherwise inferred from the order in the file relative to other plugins.
-
-. You need to copy an entry like the above, ensure the `src` URL resolves and the plugin should be loaded when the distribution is built.
-
-. If you are building locally you likely need to run an `npm run bundle` command in each plugin to make the `dist` folder, containing a single JavaScript file with the plugin available to OpenSCD.
-
-==== Within an OpenSCD core distribution
-
-Within an OpenSCD core distribution, plugins are also loaded from a json file with a slightly different schema.
-
-. Typically the distribution will be served from a static web page and within the web page there will be a plugins property declared on an `open-scd` object, for instance:
-+
-[source,js,subs=+attributes]
-----
-include::demo/index.html[tag=plugins]
-----
-
-. This plugin is an editor plugin, editor plugins are an array of JSON of the following form:
-+
-[source,js,subs=+attributes]
-----
-{
-  "name": "{plugin-name}", // <.>
-  "translations": { // <.>
-    "de": "Überwachung", 
-    "pt":"Supervisão"
-  },
-  "icon": "link", // <.>
-  "active": true, // <.>
-  "requireDoc": true, // <.>
-  "src": "/dist/oscd-supervision.js" // <.>
-}
-----
-<.> Name of the plugin which appears in the editor menu at top of screen
-<.> Translations of the plugin name as required using standard locale names.
-<.> A material icon, see others at {uri-material-icons}[Material Symbols and Icons]
-<.> Whether the plugin is enabled by default or has to be enabled in the plugins menu
-<.> Whether a document must be loaded for this plugin to be available
-<.> URL which can be a local or remote resource. 
-For a local resource, begins with a forward slash, e.g. `plugins/oscd-supervision/dist/oscd-supervision.js`. 
-In this case what is shown is loading a plugin from the internet using the continuous integration build process.
-
-. You need to copy an entry like the above, ensure the `src` URL resolves and the plugin should be loaded when the distribution is built.
-
-. If you are building locally you likely need to run an `npm run bundle` command in each plugin to make the `dist` folder, containing a single JavaScript file with the plugin available to OpenSCD.
-
-== Development
-
-=== Linting and formatting
-
-To scan the project for linting and formatting errors, run
-
-[source,bash]
-----
-npm run lint
-----
-
-To automatically fix linting and formatting errors, run
-
-[source,bash]
-----
-npm run format
-----
-
-=== Testing with Web Test Runner
-
-To execute a single test run:
-
-[source,bash]
-----
-npm run test
-----
-
-To run the tests in interactive watch mode run:
-
-[source,bash]
-----
-npm run test:watch
-----
-
-=== Tooling configs
-
-For most of the tools, the configuration is in the `package.json` to reduce the number of files in your project.
-
-If you customize the configuration a lot, you can consider moving them to individual files.
-
-=== Local Demo with `web-dev-server`
-
-To run a local development server that serves the basic demo located in `demo/index.html`
-
-[source,bash]
-----
-npm start
-----
-
-== Credit
-
-This plugin was refactored from base code in OpenSCD and relies on the code, architecture and review effort of multiple people other than the authors of this plugin, including:
-
-* Jakob Vogelsang
-* Juan Munoz
+See the {uri-docs}[documentation] for more information or {uri-openscd-core-plugin-demo}[try it out standalone].
 
-© 2023 OpenSCD Daniel Mulholland
+© 2024 OpenSCD Daniel Mulholland

antora.yml

@@ -0,0 +1,10 @@
+name: oscd-supervision
+title: Supervision
+version: dev
+prerelease: true
+start_page: introduction.adoc
+asciidoc:
+  attributes:
+    prerelease: true
+nav:
+  - modules/ROOT/nav.adoc

demo/index.deploy.html

@@ -15,12 +15,12 @@
 <!-- tag::plugins[] -->
 <open-scd
   plugins='{
-  "menu": 
+  "menu":
   [
-    {"name": "Open File", "translations": {"de": "Datei öffnen"}, "icon": "folder_open", "active": true, "src": "https://openscd.github.io/oscd-open/oscd-open.js"}, 
+    {"name": "Open File", "translations": {"de": "Datei öffnen"}, "icon": "folder_open", "active": true, "src": "https://openscd.github.io/oscd-open/oscd-open.js"},
     {"name": "Save File", "translations": {"de": "Datei speichern"}, "icon": "save", "active": true, "src": "https://openscd.github.io/oscd-save/oscd-save.js"}
   ],
-  "editor": 
+  "editor":
   [
     {"name": "Supervision", "translations": {"de": "Überwachung", "pt":"Supervisão"},  "icon": "ecg", "active": true, "src": "oscd-supervision.js"}
   ]
@@ -42,7 +42,7 @@
 </script>
 
 <script type="module">
-  import 'https://openscd.github.io/open-scd-core/open-scd.js';
+  import 'https://omicronenergyoss.github.io/open-scd-core/open-scd.js';
   //   import 'open-scd-core/open-scd.js'
   //   TODO: Could also use: jsdelivr or unpkg
 

docs/media/screenshot-add-extension.png

@@ -0,0 +1,6 @@
+* xref:ROOT:introduction.adoc[]
+* xref:ROOT:usage.adoc[]
+* xref:ROOT:allowing_supervision_modifications.adoc[]
+* xref:ROOT:installation.adoc[]
+* xref:ROOT:support.adoc[]
+* xref:ROOT:development.adoc[]