Add menu grouping in sidebar, prepare for better UI doc integration (#…

…2198) * Add menu grouping in sidebar, prepare for better UI doc integration Signed-off-by: Stefan Höhn <[email protected]> * review comments Signed-off-by: Stefan Höhn <[email protected]> * Markdown fixes Signed-off-by: Stefan Höhn <[email protected]> --------- Signed-off-by: Stefan Höhn <[email protected]>
openhab · Jan 15, 2024 · 358665e · 358665e
1 parent fb15ced
commit 358665e
Show file tree

Hide file tree

Showing 35 changed files with 468 additions and 269 deletions.
diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js
@@ -7,29 +7,41 @@ module.exports = [
     ]
   },
   {
-    title: 'Getting Started',
-    collapsable: false,
-    children: [
-      ['tutorial/', 'Tutorial Overview'],
-      'tutorial/first_steps',
-      'tutorial/things_simple',
-      'tutorial/things_intermediate',
-      'tutorial/things_advanced',
-      'tutorial/model',
-      'tutorial/persistence',
-      'tutorial/pages_intro',
-      'tutorial/auto_overview',
-      'tutorial/item_widgets',
-      'tutorial/custom_widgets',
-      'tutorial/rules_introduction',
-      'tutorial/rules_overview',
-      'tutorial/rules_basic',
-      'tutorial/rules_blockly',
-      'tutorial/rules_advanced',
-      'tutorial/rules_scenes',
-      'tutorial/tips-and-tricks'
-    ]
-  },
+      title: 'Getting Started',
+      collapsable: false,
+      children: [
+        ['tutorial/', 'Tutorial Overview'],
+        'tutorial/first_steps',
+        { title: 'Adding Things',
+          children: [
+            'tutorial/things_simple',
+            'tutorial/things_intermediate',
+            'tutorial/things_advanced',
+          ]
+        },
+        'tutorial/model',
+        'tutorial/persistence',
+        { title: 'Pages',
+          children: [
+            'tutorial/pages_intro',
+            'tutorial/auto_overview',
+            'tutorial/item_widgets',
+            'tutorial/custom_widgets'
+          ]
+        },
+        { title: 'Rules',
+          children: [
+            'tutorial/rules_introduction',
+            'tutorial/rules_overview',
+            'tutorial/rules_basic',
+            'tutorial/rules_blockly',
+            'tutorial/rules_advanced',
+            'tutorial/rules_scenes',
+          ]
+        },
+        'tutorial/tips-and-tricks'
+      ]
+    },
   {
     title: 'Installation Guide',
     collapsable: false,
@@ -63,18 +75,38 @@ module.exports = [
     title: 'Configuration Guide',
     collapsable: false,
     children: [
-      ['configuration/', 'Configuration Overview'],
-      'configuration/editors',
-      'configuration/addons',
-      'configuration/things',
-      'configuration/items',
-      'configuration/persistence',
-      'configuration/rules-dsl',
-      ['configuration/blockly/', 'Blockly Rules'],
-      'configuration/transformations',
+      { title: 'Configuration Overview',
+        path: '/docs/configuration/',
+        children: [
+          'configuration/editors',
+          'configuration/addons',
+          'configuration/things',
+          'configuration/items',
+          'configuration/persistence',
+          'configuration/rules-dsl',
+          'configuration/transformations',
+          { title: 'Blockly Rules',
+            path: '/docs/configuration/blockly/',
+            children: [
+              ['configuration/blockly/rules-blockly-items-things', 'Items & Things'],
+              ['configuration/blockly/rules-blockly-timers-and-delays', 'Timers & Delays'],
+              ['configuration/blockly/rules-blockly-voice-and-multimedia', 'Voice & Multimedia'],
+              ['configuration/blockly/rules-blockly-uom', 'Units of Measurements'],
+              ['configuration/blockly/rules-blockly-date-handling', 'Date Handling'],
+              ['configuration/blockly/rules-blockly-ephemeris', 'Ephemeris'],
+              ['configuration/blockly/rules-blockly-notifications', 'Notifications'],
+              ['configuration/blockly/rules-blockly-persistence', 'Persistence'],
+              ['configuration/blockly/rules-blockly-value-storage', 'Value Storage'],
+              ['configuration/blockly/rules-blockly-run-and-process', 'Run & Process'],
+              ['configuration/blockly/rules-blockly-logging', 'Logging'],
+              ['configuration/blockly/rules-blockly-standard-ext', 'Standard Extensions'],
+            ]
+          },
+        ]
+      },
       'configuration/actions',
-      'configuration/iconsets/classic/',
       'configuration/jsr223',
+      'configuration/iconsets/classic/',
       'configuration/services',
       'configuration/multimedia',
       ['configuration/restdocs', 'REST API'],
@@ -83,34 +115,42 @@ module.exports = [
       ['configuration/migration/', 'Migration from openHAB 2']
     ]
   },
-    {
-      title: 'Settings',
-      collapsable: false,
-      children: [
-        ['settings/', 'Settings Overview'],
-        'settings/aboutpage',
-        'settings/configuration',
-        ['settings/automations', 'Automation'],
-        'settings/addons',
-        'settings/services_system',
-        'settings/services_other',
-      ]
-    },
+  {
+    title: 'Main UI',
+    collapsable: false,
+    children: [
+      ['ui/mainui', 'Main UI'],
+      { title: 'Settings',
+        path: '/docs/settings/',
+        children: [
+          'settings/configuration',
+          ['settings/automations', 'Automation'],
+          ['settings/system_settings', 'System'],
+          ['settings/addons', 'Add-ons'],
+        ]
+      },
+      ['ui/addons-store', 'Add-on Store'],
+      ['ui/developer-tools', 'Developer Tools'],
+      ['ui/aboutpage', 'Help & About'],
+    ]
+  },
   {
     title: 'User Interface Guide',
     collapsable: false,
     children: [
       'ui/',
       'ui/sitemaps',
-      'ui/layout-pages',
-      'ui/map-pages',
-      'ui/floorplan-pages',
-      'ui/tabbed-pages',
-      'ui/chart-pages',
-      ['ui/building-pages', 'Building Pages'],
-      'ui/personal-widgets',
-      'ui/widget-expressions-variables',
-      'ui/css-pages-widgets',
+      { title: 'Pages',
+        children: [
+          'ui/layout-pages',
+          'ui/map-pages',
+          'ui/floorplan-pages',
+          'ui/tabbed-pages',
+          'ui/chart-pages',
+          ['ui/building-pages', 'Building Pages'],
+        ]
+      },
+      ['ui/personal-widgets', 'Creating Personal Widgets'],
       ['ui/components/', 'Component Reference'],
       'ui/habpanel/habpanel',
       ['apps/android', 'Android App'],
@@ -145,7 +185,7 @@ module.exports = [
   },
   {
     title: 'Developer Guide',
-    collapsable: false,
+    collapsable: true,
     children: [
       ['developer/', 'Overview & Introduction'],
       'developer/guidelines',
@@ -160,7 +200,7 @@ module.exports = [
   },
   {
     title: 'Developer Appendix',
-    collapsable: false,
+    collapsable: true,
     children: [
       'developer/buildsystem',
       'developer/osgi/osgi',

diff --git a/.vuepress/styles/index.styl b/.vuepress/styles/index.styl
@@ -29,7 +29,7 @@
         // background-color white
         background-color rgba(98%, 98%, 99%, 0.96) !important
         box-shadow rgba(10%,10%,10%,25%) 0 0 5px
-    
+
     .nav-item a
         // font-family 'Open Sans', sans-serif
         font-weight 400
@@ -59,6 +59,12 @@
 .dropdown-wrapper .nav-dropdown .dropdown-item h4
     margin-bottom .2rem
 
+.sidebar-group.is-sub-group>.sidebar-heading:not(.clickable)
+    opacity 1 !important
+
+.arrow.right
+    border-left: 6px solid #333 !important
+
 .sidebar
     background-color #f7f7f7 !important
     // background linear-gradient(90deg, #fff0e0, #fff) !important

diff --git a/configuration/blockly/rules-blockly-uom.md b/configuration/blockly/rules-blockly-uom.md
@@ -1,6 +1,6 @@
 ---
 layout: documentation
-title: Rules Blockly - Items & Things
+title: Rules Blockly - Units of Measurements
 ---
 <!-- markdownlint-disable MD036 -->
 

diff --git a/settings/images/play-rule.png → configuration/images/rule-play-audio.png b/settings/images/play-rule.png → configuration/images/rule-play-audio.png
diff --git a/configuration/multimedia.md b/configuration/multimedia.md
@@ -11,12 +11,16 @@ The framework supports some base [functions](https://openhab.org/javadoc/latest/
 
 ### Actions
 
+You can set and get the volume in DSL rules by using these functions:
+
 - `setMasterVolume(float volume)` : Sets the volume of the host machine (volume in range 0-1)
 - `setMasterVolume(PercentType percent)` : Sets the volume of the host machine
 - `increaseMasterVolume(float percent)` : Increases the volume by the given percent
 - `decreaseMasterVolume(float percent)` : Decreases the volume by the given percent
 - `float getMasterVolume()` : Returns the current volume as a float between 0 and 1
 
+Please refer to the documentation of the [Automation add-ons](/addons/#automation) on how to use these actions from the respective language, e.g. JavaScript or JRuby.
+
 ## Audio Capture
 
 openHAB is able to capture audio.
@@ -55,8 +59,16 @@ 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.
+
 Additionally, certain bindings register their supported devices as audio sinks, e.g. Sonos speakers.
 
+### Default Audio Sink
+
+You can configure a default audio sink, which will be used if no audio sink is provided in audio and voice actions.
+
+You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI by visitting the **Settings** page and opening **System Settings** -> **Audio**.
+
 ### Console commands
 
 To check which audio sinks are available, you can use the console:
@@ -67,8 +79,6 @@ openhab> openhab:audio sinks
   Web Audio (webaudio)
 ```
 
-You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Audio`.
-
 In order to play a sound, you can use the following commands on the console:
 
 ```text
@@ -97,6 +107,17 @@ Alternatively the [`playSound()`](https://www.openhab.org/javadoc/latest/org/ope
 - `playStream(String url)` : plays an audio stream from an url to the default sink (set url to `null` if streaming should be stopped)
 - `playStream(String sink, String url)` : plays an audio stream from an url to the given sink(s) (set url to `null` if streaming should be stopped)
 
+If no audio sink is provided, the default audio sink will be used.
+
+Please refer to the documentation of the [Automation add-ons](/addons/#automation) on how to use these actions from the respective language, e.g. JavaScript or JRuby.
+
+UI-based rules support audio actions as well.
+Just create or edit a rule, add a new action, select "Audio & Voice" and the UI will then guide you trough the setup:
+
+![Audio action setup in the UI](images/rule-play-audio.png)
+
+Visit the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html) to learn how to use audio actions from Blockly.
+
 #### Examples
 
 ```java
@@ -109,12 +130,18 @@ playStream("example.com")
 playStream("sonos:PLAY5:kitchen", "example.com")
 ```
 
+You will find more examples in the documentation of the [Automation add-ons](/addons/#automation) and the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html).
+
 ## Voice
 
 ### Text-to-Speech
 
 In order to use text-to-speech, you need to install at least one [TTS service](/addons/#voice).
 
+#### Default TTS Service & Voice
+
+You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI by visitting the **Settings** page and opening **System Settings** -> **Voice**.
+
 #### Console Commands
 
 To check which Text-to-Speech services are available, you can use the console:
@@ -147,8 +174,6 @@ openhab> openhab:voice voices
   VoiceRSS - vietnamien (Vietnam) - default (voicerss:viVN)
 ```
 
-You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Voice`.
-
 In order to say a text, you can enter such a command on the console (The default voice and default audio sink will be used):
 
 ```text
@@ -169,6 +194,14 @@ Alternatively you can execute such commands within DSL rules by using the [`say(
 You can select a particular voice (second parameter) and a particular audio sink (third parameter).
 If no voice or no audio sink is provided, the default voice and default audio sink will be used.
 
+Please refer to the documentation of the [Automation add-ons](/addons/#automation) on how to use these actions from the respective language, e.g. JavaScript or JRuby.
+
+UI-based rules support voice actions as well.
+Just create or edit a rule, add a new action, select "Audio & Voice" and the UI will then guide you trough the setup.
+The presented dialog will look similar to the one shown [above](#actions-2).
+
+Visit the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html) to learn how to use voice actions from Blockly.
+
 ##### Examples
 
 ```java
@@ -180,6 +213,8 @@ say("Hello world!", "voicerss:enUS", "sonos:PLAY5:kitchen")
 say("Hello world!", "voicerss:enUS", "sonos:PLAY5:kitchen", new PercentType(25))
 ```
 
+You will find more examples in the documentation of the [Automation add-ons](/addons/#automation) and the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html).
+
 ### Speech-to-Text
 
 In order to use Speech-to-Text, you need to install at least one [STT service](/addons/#voice).

diff --git a/configuration/rules-dsl.md b/configuration/rules-dsl.md
@@ -1,6 +1,6 @@
 ---
 layout: documentation
-title: Rules
+title: Textual Rules
 ---
 
 # Textual Rules

diff --git a/introduction.md b/introduction.md
@@ -163,7 +163,7 @@ Once you have got a first overview, it is time to practice.
 Here a short list of the steps that you will need to consider to get openHAB up and running as your home automation system:
 
 1. Install openHAB
-1. If you already own a smart device, search the addons for the brand or technology used by that device (or simply browse the list of [add-ons](/addons/) for any technologies or services you may recognize)
+1. If you already own a smart device, search the add-ons for the brand or technology used by that device (or simply browse the list of [add-ons](/addons/) for any technologies or services you may recognize)
 1. Install a binding (in openHAB)
 1. Define a “thing”
 1. Add a “channel” to the “thing” if not created by the binding