[Enhancement] - Simplify local builds to lower bar for beginners #2215 (#2218)

* [Enancement] - Simplify local builds to lower bar for beginners
Fixes #2215

* [Enancement] - Simplify local builds to lower bar for beginners
Fixes #2215

📄 missing `npm install step` added to README.md

Signed-off-by: Patrik Gfeller <patrik.gfeller@gmail.com>

* 🐞 problems resolved after reabse/update to latest main branch.

Signed-off-by: Patrik Gfeller <patrik.gfeller@gmail.com>

* 🔃 Squashed commit of the following:

commit 6774910167
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sun Feb 25 17:23:01 2024 +1000

    Convert pwm, pid, map icons to svg and add jinja logo (#2253)

    * Replace map icon with svg version

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

    * Replace pidcontroller icon with svg version

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

    * Replace pwm icon with svg version

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

    * Add jinja logo

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

    ---------

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit 6f39e146f4
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sun Feb 25 08:15:21 2024 +1000

    Add icon for scale transformation (#2252)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit 67a019a2df
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sun Feb 25 00:55:02 2024 +1000

    Add pwm icon (#2251)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit a03e4c072b
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sun Feb 25 00:54:22 2024 +1000

    PIDController icon: Make lines thicker (#2250)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit 7308a413a0
Author: Kai Kreuzer <kai@openhab.org>
Date:   Sat Feb 24 14:57:54 2024 +0100

    Fix typo in tutorial (#2249)

    Signed-off-by: Kai Kreuzer <kai@openhab.org>

commit ccb7e64bf0
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sat Feb 24 18:15:21 2024 +1000

    Make basicui icon a bit bigger and more visible (#2247)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit d9664d9ac4
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sat Feb 24 18:10:22 2024 +1000

    Add icon for pidcontroller (#2248)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit bcba38ebb3
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sat Feb 24 08:31:23 2024 +1000

    Add an icon for map transformation (#2240)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit f8ebab4e33
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Sat Feb 24 03:23:06 2024 +1000

    Add icon for Basic UI (#2242)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

commit ab958f9397
Author: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Date:   Fri Feb 23 18:21:57 2024 +0100

    Bump ip from 1.1.5 to 1.1.9 (#2244)

    Bumps [ip](https://github.com/indutny/node-ip) from 1.1.5 to 1.1.9.
    - [Commits](https://github.com/indutny/node-ip/compare/v1.1.5...v1.1.9)

    ---
    updated-dependencies:
    - dependency-name: ip
      dependency-type: indirect
    ...

    Signed-off-by: dependabot[bot] <support@github.com>
    Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
    Co-authored-by: stefan-hoehn <mail@stefanhoehn.com>

commit dedb16a37c
Author: Florian Hotze <florianh_dev@icloud.com>
Date:   Fri Feb 23 16:52:57 2024 +0100

    Use SVG logos for DoorBird & Govee (#2246)

    Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

commit 749a656520
Author: jimtng <2554958+jimtng@users.noreply.github.com>
Date:   Fri Feb 23 18:29:36 2024 +1000

    Add sqlite icon (#2238)

    Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>

Signed-off-by: Patrik Gfeller <patrik.gfeller@gmail.com>

* Update README.md

Signed-off-by: stefan-hoehn <mail@stefanhoehn.com>

* Update README.md

Signed-off-by: stefan-hoehn <mail@stefanhoehn.com>

---------

Signed-off-by: Patrik Gfeller <patrik.gfeller@gmail.com>
Signed-off-by: stefan-hoehn <mail@stefanhoehn.com>
Co-authored-by: stefan-hoehn <mail@stefanhoehn.com>

.vuepress/.gitignore

@@ -1,3 +1,4 @@
 addons-*
 public/logos
 tmp
+dist

.vuepress/config.js

@@ -1,94 +0,0 @@
-const DocsSidebarNavigation = require('./docs-sidebar.js')
-
-const fs = require ('fs-extra')
-const path = require('path')
-// const CopyWebpackPlugin = require('copy-webpack-plugin')
-
-const HighlightDsl = require('./highlight-dsl')
-const HighlightRules = require('./highlight-rules')
-
-const base = process.env.OH_DOCS_VERSION ? `/v${process.env.OH_DOCS_VERSION}/` : '/'
-
-module.exports = {
-  title: 'v4 Documentation Preview',
-  description: 'This is a preview of the main parts of the documentation, found in the openhab/openhab-docs repository',
-  dest: 'vuepress',
-  host: 'localhost',
-  plugins: ['tabs', 'container'],
-  base,
-  head: [
-    ['link', { rel: 'stylesheet', href: `/fonts/fonts.css` }],
-    ['link', { rel: 'icon', href: `/favicon.ico` }],
-    ['link', { rel: 'shortcut icon', href: `/favicon.ico` }],
-    ['link', { rel: 'apple-touch-icon', href: `/apple-icon.png` }],
-    // ['link', { rel: 'stylesheet', href: `https://fonts.googleapis.com/css?family=Open+Sans:300,400` }],
-    ['meta', { property: 'og:type', content: 'website' }],
-    ['meta', { property: 'og:image', content: 'https://www.openhab.org/og-image.png' }],
-    // ['meta', { property: 'og:title', content: 'openHAB' }],
-    // ['meta', { property: 'og:description', content: 'a vendor and technology agnostic open source automation software for your home' }],
-    // ['script', { src: `https://identity.netlify.com/v1/netlify-identity-widget.js` }]
-  ],
-  extendMarkdown(md) {
-    md.options.linkify = true
-    const highlight = md.options.highlight
-    md.options.highlight = (str, lang) => {
-      if (!Prism.languages.dsl || !Prism.languages.rules) {
-        Prism.languages.dsl = HighlightDsl
-        Prism.languages.rules = HighlightRules
-      }
-
-      if (['nginx', 'bash', 'python', 'js', 'javascript', 'groovy'].indexOf(lang) >= 0) return highlight(str, lang)
-
-      /* Simple heuristics to detect rules & other openHAB DSL code snippets and override the language */
-      if (str.match(/\b(?:Color|Contact|Dimmer|Group|Number|Player|Rollershutter|Switch|Location|Frame|Default|Text|Group|Selection|Setpoint|Slider|Colorpicker|Chart|Webview|Mapview|Image|Video|Item|Thing|Bridge|Time|Type|Sitemap|sitemap)\b/)) {
-        lang = 'dsl'
-      }
-      if (str.match(/\b(?:String|DateTime)\b/) && lang !== 'java' && lang !== 'xml') {
-        lang = 'dsl'
-      }
-      if ((str.match(/\brule\b/) && str.match(/\bwhen\b/) && str.match(/\bthen\b/) && str.match(/\bend\b/)) ||
-        str.match(/received update/) || str.match(/changed.*(?:from|to)/) || str.match(/Channel.*triggered/) ||
-        str.match(/\bval\b/) || str.match(/\bvar\b/) /* <-- dangerous! */) {
-        
-        lang = 'rules'
-      }
-      if (lang === 'shell' || lang === 'sh' || lang === 'shell_session') lang = 'bash'
-      if (lang === 'conf') lang = 'dsl'
-      if (lang === 'JSON') lang = 'json'
-      // if (lang === 'xtend' || lang === 'text' || !lang) {
-      //   console.log('Cannot determine language of code: ' + lang)
-      //   console.log(str)
-      // }
-
-      return highlight(str, lang)
-    }
-  },
-  // configureWebpack: (config, isServer) => {
-  //   config.plugins.push(new CopyWebpackPlugin([
-  //     { from: '.vuepress/_redirects', to: '.'},
-  //     { from: '.vuepress/_headers', to: '.'},
-  //   ]))
-  // },
-  serviceWorker: false,
-  themeConfig: {
-    logo: `/openhab-logo.png`,
-    // repo: 'openhab',
-    editLinks: false,
-    activeHeaderLinks: false,
-    sidebarDepth: 0,
-    docsDir: 'docs',
-    nav: [
-      {
-        text: 'Documentation',
-        link: '/docs/',
-      },
-      {
-        text: 'GitHub',
-        link: 'https://github.com/openhab/openhab-docs',
-      }
-    ],
-    sidebar: {
-      '/docs/': DocsSidebarNavigation
-    }
-  }
-}

.vuepress/config.ts

@@ -0,0 +1,67 @@
+import { DefaultThemeConfig, UserConfig, defineConfig } from "vuepress/config";
+
+const DocsSidebarNavigation = require('./docs-sidebar.js')
+
+const base = process.env.OH_DOCS_VERSION
+    ? `/v${process.env.OH_DOCS_VERSION}/`
+    : '/'
+
+const config: UserConfig<DefaultThemeConfig> = {
+    title: 'v4 Documentation Preview',
+    description: 'This is a preview of the main parts of the documentation, found in the openhab/openhab-docs repository',
+    dest: 'vuepress',
+    host: 'localhost',
+    plugins: [
+        // @ts-ignore
+        'tabs',
+        'container'
+    ],
+    // @ts-ignore
+    base: base,
+    patterns: [
+        'docs/**/*.md',
+        'addons/integrations/**/*.md',
+        '**/*.vue'],
+    configureWebpack: {
+        module: {
+            rules: [
+                {
+                    test: /\.(drawio|xml|txt)$/,
+                    exclude: /node_modules/,
+                    use: 'null-loader'
+                }
+            ]
+        }
+    },
+    head: [
+        ['link', { rel: 'stylesheet', href: `/fonts/fonts.css` }],
+        ['link', { rel: 'icon', href: `/favicon.ico` }],
+        ['link', { rel: 'shortcut icon', href: `/favicon.ico` }],
+        ['link', { rel: 'apple-touch-icon', href: `/apple-icon.png` }],
+        ['meta', { property: 'og:type', content: 'website' }],
+        ['meta', { property: 'og:image', content: 'https://www.openhab.org/og-image.png' }],
+
+    ],
+    themeConfig: {
+        logo: `/openhab-logo.png`,
+        editLinks: false,
+        activeHeaderLinks: false,
+        sidebarDepth: 0,
+        docsDir: 'docs',
+        nav: [
+            {
+                text: 'Documentation',
+                link: '/docs/',
+            },
+            {
+                text: 'GitHub',
+                link: 'https://github.com/openhab/openhab-docs',
+            }
+        ],
+        sidebar: {
+            '/docs/': DocsSidebarNavigation
+        }
+    }
+};
+
+export default defineConfig(config);

README.md

@@ -50,12 +50,6 @@ Imagine you want to do an improvement of the zwave binding and have to update th
 That's twice the effort and also we would have to coordinate two Pull Requests.
 So we are saving time for everyone by keeping those files at their original location along with the code.
 
-::: tip UNDER REVIEW
-
-The process below is subject to changes until the openHAB.x website become the production one.
-
-:::
-
 ### How the documentation build works
 
 We have set up our [build server](https://ci.openhab.org/view/Documentation/) to do the magic automatically.
@@ -85,6 +79,40 @@ When one of these jobs is finished, it will then notify our website hosting serv
 This is recognized due to new commits in the final branch of this repository.
 The new build will include all the latest changes in the code repository and in all external repositories.
 
+### How to build the documentation locally
+
+It is possible to build a preview version of the documentation on your local machine. The following software is required:
+
+- [`node =16.20.1`](https://nodejs.org/en)
+- [`ruby >=3.0.2`](https://www.ruby-lang.org/en/)
+- [`Python >= 3.10.12`](https://www.python.org)
+
+If you work on multiple node projects [Node Version Manager](https://github.com/nvm-sh/nvm) is recommended in case they use a different version of node.
+
+Example:
+
+```bash
+$ nvm install 16
+# ...
+$ nvm use 16
+Now using node v16.20.2 (npm v8.19.4)
+$ npm install
+# ...
+$ npm run serve
+# ...
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)
+```
+
+The local preview is available under the following options
+
+- [http://0.0.0.0:8000/docs](http://0.0.0.0:8000/docs)
+- [http://localhost:8000/docs](http://localhost:8000/docs)
+- [http://[::]/:8000/docs](http://[::]:8000/docs)
+
+![local preview](images/local-docu-preview.png)
+
+This will also allow you to preview how the page renders on different devices using the respective browser tools.
+
 ## Documentation Versioning
 
 Just as openHAB is released in versions, the documentation website provides fixed versions of the documentation articles, e.g., [https://www.openhab.org/v2.2/installation/linux.html](https://www.openhab.org/v2.2/installation/linux.html)

package.json

@@ -1,13 +1,20 @@
 {
   "name": "openhab-docs",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "openHAB Documentation",
   "main": "index.js",
   "scripts": {
-    "prepare-docs": "ruby prepare-docs.rb",
+    "build-only": "vuepress build .",
-    "build-preview": "ruby prepare-docs.rb --delete-sources && vuepress build .",
+    "prebuild-preview-local": "ruby prepare-docs.rb",
-    "build-preview-local": "ruby prepare-docs.rb && vuepress build .",
+    "build-preview-local": "cross-env LANG=en_US.UTF-8 LANGUAGE=en_US.UTF-8 LC_ALL=en_US.UTF-8 NODE_OPTIONS=--openssl-legacy-provider && npx vuepress build .",
-    "build-only": "vuepress build ."
+    "build-preview": "npm run build-only",
+    "postinstall": "npm dedupe && npm prune",
+    "prebuild-preview": "ruby prepare-docs.rb",
+    "preserve": "npm run build-preview-local",
+    "serve": "python3 -m http.server --directory vuepress"
+  },
+  "engines": {
+    "node": ">=16.20.1 <17"
   },
   "repository": {
     "type": "git",
@@ -20,10 +27,17 @@
   },
   "homepage": "https://github.com/openhab/openhab-docs#readme",
   "dependencies": {
+    "cross-env": "^7.0.3",
+    "null-loader": "^4.0.1",
     "vue-tabs-component": "^1.5.0",
-    "vuepress": "^1.5.0",
+    "vuepress": "^1.9.10",
     "vuepress-plugin-container": "^2.1.4",
     "vuepress-plugin-tabs": "^0.3.0",
-    "webpack-serve": "^3.1.1"
+    "webpack-serve": "^3.2.0"
+  },
+  "overrides": {
+    "vue": "=2.6.14",
+    "vue-server-renderer": "=2.6.14",
+    "vue-template-compiler": "=2.6.14"
   }
 }

prepare-docs.rb

@@ -32,16 +32,6 @@ end
 process_main_docs(".")
 add_placeholder_pages()
 
-
-
-if (ARGV[0] && ARGV[0] == "--delete-sources") then
-    puts ">>> !!! Deleting source files - for ephemeral clones only!"
-    FileUtils.rm_rf(Dir.glob("addons/*.md"))
-    ["administration", "appendix", "community", "configuration", "developers", "installation", "tutorials"].each { |d|
-        FileUtils.rm_rf(d)
-    }
-end
-
 # Regenerate the classic iconset docs
 #puts ">>> Generating iconset"
 #system("ruby generate_iconset_doc.rb #{docs_source_dir}/_addons_iconsets classic #{docs_source_dir}/_data docs/configuration/iconsets")

styleguide.md

@@ -28,4 +28,4 @@ An unordered loose list (applied if bigger or with nested lists):
 
 - Some more text
 
-- And even more text that could also strech over multiple lines
+- And even more text that could also stretch over multiple lines