Add Main UI docs for integration into sidebar help (openhab#2199)

* Add Main UI docs structure & Migrate UI-integrated docs Signed-off-by: Florian Hotze <[email protected]> * Add some links Signed-off-by: Florian Hotze <[email protected]> * Add CONTRIBUTING.md Signed-off-by: Florian Hotze <[email protected]> * Update icon comments for UI code change Signed-off-by: Florian Hotze <[email protected]> * Fix markdownlint Signed-off-by: Florian Hotze <[email protected]> * Migrate existing MainUI settings documentation Signed-off-by: Florian Hotze <[email protected]> * Fix build & Update sidebar Signed-off-by: Florian Hotze <[email protected]> * Update img links Signed-off-by: Florian Hotze <[email protected]> * Migrate docs from the UI section Signed-off-by: Florian Hotze <[email protected]> * Add persistence docs Signed-off-by: Florian Hotze <[email protected]> * Fixes & Improvements Signed-off-by: Florian Hotze <[email protected]> * Update CONTRIBUTING.md Signed-off-by: Florian Hotze <[email protected]> * Address review Signed-off-by: Florian Hotze <[email protected]> --------- Signed-off-by: Florian Hotze <[email protected]>
dilyanpalauzov · Jan 26, 2024 · 321c8de · 321c8de
1 parent 07e189b
commit 321c8de
Show file tree

Hide file tree

Showing 56 changed files with 821 additions and 560 deletions.
diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js
@@ -119,19 +119,25 @@ module.exports = [
     title: 'Main UI',
     collapsable: false,
     children: [
-      ['ui/mainui', 'Main UI'],
+      ['mainui/', 'Overview'],
       { title: 'Settings',
-        path: '/docs/settings/',
+        path: '/docs/mainui/settings/',
         children: [
-          'settings/configuration',
-          ['settings/automations', 'Automation'],
-          ['settings/system_settings', 'System'],
-          ['settings/addons', 'Add-ons'],
+          ['mainui/settings/things', 'Things'],
+          ['mainui/settings/model', 'Model'],
+          ['mainui/settings/items', 'Items'],
+          ['mainui/settings/pages', 'Pages'],
+          ['mainui/settings/transformations', 'Transformations'],
+          ['mainui/settings/persistence', 'Persistence'],
+          ['mainui/settings/rules', 'Rules'],
+          ['mainui/settings/scenes', 'Scenes'],
+          ['mainui/settings/scripts', 'Scripts'],
+          ['mainui/settings/schedule', 'Schedule']
         ]
       },
-      ['ui/addons-store', 'Add-on Store'],
-      ['ui/developer-tools', 'Developer Tools'],
-      ['ui/aboutpage', 'Help & About'],
+      ['mainui/addons', 'Add-on Store'],
+      ['mainui/developer/', 'Developer Tools'],
+      ['mainui/about', 'Help & About'],
     ]
   },
   {

diff --git a/.vuepress/process_main_docs.rb b/.vuepress/process_main_docs.rb
@@ -17,10 +17,7 @@ def process_main_docs(docs_source_dir)
     FileUtils.cp_r("#{docs_source_dir}/images/addons", ".vuepress/public/logos")
 
 
-
     puts ">>> Migrating the Concepts section"
-
-
     if Dir.exists?("#{docs_source_dir}/concepts") then
         Dir.glob("#{docs_source_dir}/concepts/*.md").each { |path|
             file = File.basename(path)
@@ -35,10 +32,7 @@ def process_main_docs(docs_source_dir)
     end
 
 
-
     puts ">>> Migrating the Installation section"
-
-
     Dir.glob("#{docs_source_dir}/installation/*.md") { |path|
         file = File.basename(path)
         next if file == "designer.md"
@@ -49,10 +43,7 @@ def process_main_docs(docs_source_dir)
     FileUtils.cp_r("#{docs_source_dir}/installation/images", "docs/installation/images")
 
 
-
     puts ">>> Migrating the Tutorial section"
-
-
     Dir.glob("#{docs_source_dir}/tutorials/getting_started/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
@@ -65,8 +56,6 @@ def process_main_docs(docs_source_dir)
 
 
     puts ">>> Migrating the Configuration section"
-
-
     Dir.glob("#{docs_source_dir}/configuration/*.md") { |path|
         file = File.basename(path)
         next if file == "transform.md" # Useless, copy the one from addons
@@ -81,20 +70,28 @@ def process_main_docs(docs_source_dir)
     #FileUtils.mv("docs/configuration/migration/migration.md", "docs/configuration/migration/index.md")
     #FileUtils.cp_r("#{docs_source_dir}/tutorials/images", "docs/configuration/migration")
 
-    puts ">>> Migrating the Settings section"
-
 
-    Dir.glob("#{docs_source_dir}/settings/*.md") { |path|
+    puts ">>> Migrating the Main UI section"
+    Dir.glob("#{docs_source_dir}/mainui/*.md") { |path|
+        file = File.basename(path)
+        puts " -> #{file}"
+        process_file("#{docs_source_dir}/mainui", file, "docs/mainui", "#{$docs_repo_root}/mainui/#{file}")
+    }
+    Dir.glob("#{docs_source_dir}/mainui/developer/*.md") { |path|
+        file = File.basename(path)
+        puts " -> #{file}"
+        process_file("#{docs_source_dir}/mainui/developer", file, "docs/mainui/developer", "#{$docs_repo_root}/mainui/developer/#{file}")
+    }
+    Dir.glob("#{docs_source_dir}/mainui/settings/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
-        process_file("#{docs_source_dir}/settings", file, "docs/settings", "#{$docs_repo_root}/settings/#{file}")
+        process_file("#{docs_source_dir}/mainui/settings", file, "docs/mainui/settings", "#{$docs_repo_root}/mainui/settings/#{file}")
     }
     puts " -> images"
-    FileUtils.cp_r("#{docs_source_dir}/settings/images", "docs/settings/images")
-
-    puts ">>> Migrating the Migration Tutorial section"
+    FileUtils.cp_r("#{docs_source_dir}/mainui/images", "docs/mainui/images")
 
 
+    puts ">>> Migrating the Migration Tutorial section"
     Dir.glob("#{docs_source_dir}/configuration/migration/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
@@ -103,8 +100,8 @@ def process_main_docs(docs_source_dir)
     puts " -> images"
     #FileUtils.cp_r("#{docs_source_dir}/configuration/images", "docs/configuration") // no images placed yet
 
-    puts ">>> Migrating the Blockly Tutorial section"
 
+    puts ">>> Migrating the Blockly Tutorial section"
     Dir.glob("#{docs_source_dir}/configuration/blockly/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
@@ -113,9 +110,8 @@ def process_main_docs(docs_source_dir)
     puts " -> images"
     #FileUtils.cp_r("#{docs_source_dir}/configuration/images", "docs/configuration") // no images placed yet
 
-    puts ">>> Migrating the UI section"
-
 
+    puts ">>> Migrating the UI section"
     Dir.glob("#{docs_source_dir}/ui/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
@@ -125,10 +121,7 @@ def process_main_docs(docs_source_dir)
     FileUtils.cp_r("#{docs_source_dir}/ui/images", "docs/ui/images")
 
 
-
     puts ">>> Migrating the Apps section"
-
-
     Dir.glob("#{docs_source_dir}/addons/uis/apps/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
@@ -138,10 +131,7 @@ def process_main_docs(docs_source_dir)
     FileUtils.cp_r("#{docs_source_dir}/addons/uis/apps/images", "docs/apps")
 
 
-
     puts ">>> Migrating the Administration section"
-
-
     Dir.glob("#{docs_source_dir}/administration/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
@@ -151,10 +141,7 @@ def process_main_docs(docs_source_dir)
     FileUtils.cp_r("#{docs_source_dir}/administration/images", "docs/administration/images")
 
 
-
     puts ">>> Migrating the Developer section"
-
-
     Dir.glob("#{docs_source_dir}/developers/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"

diff --git a/configuration/multimedia.md b/configuration/multimedia.md
@@ -59,7 +59,7 @@ The distribution comes with these options built-in:
 | `enhancedjavasound` | System Speaker (with mp3 support) | This uses the JRE sound drivers plus an additional 3rd party library, which adds support for mp3 files.                                                                                                                                                                                                                                                      |
 | `webaudio`          | Web Audio                         | Convenient, if sounds should not be played on the server, but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. Obviously, the browser needs to be opened and have a compatible openHAB UI running. Currently, this feature is supported by Main UI, Basic UI and HABPanel. |
 
-Please refer to the [Main UI docs]({{base}}/ui/mainui.html#web-audio-sink) for setting up web audio in Main UI.
+Please refer to the [Main UI docs]({{base}}/mainui/about.html#web-audio-sink) for setting up web audio in Main UI.
 
 Additionally, certain bindings register their supported devices as audio sinks, e.g. Sonos speakers.
 

diff --git a/developers/buildsystem.md b/developers/buildsystem.md
@@ -48,7 +48,7 @@ If the embedded bundle's manifest is not properly exporting all needed packages,
 In two cases using an "external" (i.e. not embedded) dependency is required:
 
 1. Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/3.1.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/3.1.0-SNAPSHOT`).
-2. Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`).
+1. Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`).
 
 Dependencies on other openHAB bundles should always have the scope `provided`.
 To ensure that external dependencies are available at runtime they also need to be added to the `feature.xml`:

diff --git a/mainui/CONTRIBUTING.md b/mainui/CONTRIBUTING.md
@@ -0,0 +1,50 @@
+# openHAB Main UI Documentation
+
+The documentation located in this directory (`mainui`) is picked up by Main UI's sidebar help (<kbd>Shift</kbd><kbd>Alt</kbd><kbd>D</kbd>).
+
+The file structure in this directory MUST NOT be changed, otherwise Main UI won't be able to pick up the docs!
+To allow the embedding into the UI, some conventions have to be made:
+
+## Conventions
+
+In general, each `.md` file in this directory should provide a header section which is ready to be used in the UI.
+
+The content to be shown in the UI has to be enclosed into these special comments:
+
+```markdown
+<!-- START MAINUI SIDEBAR DOC - DO NOT REMOVE -->
+Lorem ipsum dolor sit amet, consectetur adipisici elit, ...
+<!-- END MAINUI SIDEBAR DOC - DO NOT REMOVE -->
+```
+
+## Features && Behaviour
+
+Inside these comments, the UI allows the following features:
+
+- Embed [Framework7 icons](https://framework7.io/icons/) into the UI-rendered docs using these comments:
+  - `<!--F7 $iconname -->`, where `$iconname` is a Framework7 icon's name
+  - `<!--F7:blue $iconame -->` to set the icon's color to blue
+  - `<!--F7:green $iconame -->` to set the icon's color to green
+
+  Please note that the docs website does NOT render these icons, so you should always describe the icon, e.g.:
+
+  ```markdown
+  Add ... using the <!--F7:blue plus_circle_fill --> plus button ...
+  ```
+
+- Link to UI pages by linking to a file relative to the current file without adding a file extension, e.g.
+  `[Rules](rules)` in [settings/index.md](settings/index.md) links to `/settings/rules/` or
+  `[Settings](settings)` in [index.md](index.md) links to `/settings/`.
+
+  **Please consider that when adding or changing links inside the UI-shown content section!**
+  If you want to make sure you don't break anything, never change links without actually testing the consequences in Main UI.
+
+- Link to other documentation pages by using links starting with ``{{base}}`` (recommended) or `/docs`, e.g.
+  `[Inbox]({{base}}/tutorial/things_simple.html#accept-the-light-bulb-things)`
+
+The following is not supported:
+
+- Images are not loaded and not rendered, which means you can use images inside the comments, but they will only be shown on the website.
+- `[Section A](#section-a)` links are currently not supported in the UI.
+
+For advanced information on how the UI manipulates the documentation before rendering it, please have a look at the [source code](https://github.com/openhab/openhab-webui/blob/main/bundles/org.openhab.ui/web/src/components/developer/help/context.vue).