Describe how to use build artifact from a docu repo PR to create the webpage

.gitignore

@@ -66,6 +66,3 @@ typings/
 
 # VuePress dist
 vuepress
-
-# openhab-docs in .vuepress
-.vuepress/openhab-docs

.nvmrc

@@ -0,0 +1 @@
+16

.vscode/settings.json

@@ -1,3 +1,7 @@
 {
-    "editor.tabSize": 2
+    "editor.tabSize": 2,
+    "editor.formatOnSave": true,
+    "[ruby]": {
+        "editor.defaultFormatter": "testdouble.vscode-standard-ruby"
+    }
 }

.vuepress/.gitignore

@@ -2,3 +2,4 @@ addons-*
 public/logos
 thing-types.json
 tmp
+openhab-docs

.vuepress/config.js

@@ -25,12 +25,13 @@ const feedOptions = {
 
 const noAddons = process.env.OH_NOADDONS
 
+let docsVersion;
 if (!process.env.OH_DOCS_VERSION) {
-  throw new Error('Please set the OH_DOCS_VERSION environment variable to the name of the branch of the openhab-docs repo that has been prepared')
+  docsVersion = 'Pull Request'
+} else {
+  docsVersion = process.env.OH_DOCS_VERSION.replace('final-stable', 'Stable').replace('final-', '').replace('final', 'Latest').replace('.x', '')
 }
 
-const docsVersion = process.env.OH_DOCS_VERSION.replace('final-stable', 'Stable').replace('final-', '').replace('final', 'Latest').replace('.x', '')
-
 module.exports = {
   title: 'openHAB',
   description: 'openHAB - a vendor and technology agnostic open source automation software for your home',

CONTRIBUTING.md

@@ -2,17 +2,17 @@
 
 This website is made with [VuePress](https://vuepress.vuejs.org/).
 It will be installed as part of the dev dependencies.
-For the used version of vuepress to work correctly, Node.js 16.20.0 or **older** is needed. 
+For the used version of vuepress to work correctly, Node.js 16.20.0 or **older** is needed.
 Alternatively on newer versions [the legacy OpenSSL provider can be enabled as described in this StackOverflow thread](https://stackoverflow.com/questions/69692842/error-message-error0308010cdigital-envelope-routinesunsupported).
 For the Ruby scripts used by the website build, Ruby 2.4.3 is needed.
 If you are using a Node.js version manager like [fnm](https://github.com/Schniz/fnm), the provided `.node-version` file should automatically set the correct Node.js version needed.
 If you are using a Ruby version manager like [rvm](https://rvm.io/), running `rvm use` should automatically set the correct version according to the `.ruby-version` file.
 
 ## Editing
 
-Be careful not to edit anything in the folder vuepress as it is the folder that contains generated content. 
+Be careful not to edit anything in the folder vuepress as it is the folder that contains generated content.
 The folder that contains pages to be edited is called ".vuepress" (note the dot at the beginning of the folder name).
-You can alter layouts and components in `.vuepress/components`, or the navigation in `.vuepress/config.js` - check the VuePress docs for more details. 
+You can alter layouts and components in `.vuepress/components`, or the navigation in `.vuepress/config.js` - check the VuePress docs for more details.
 
 Note: if you add a new component and reference it in a (Markdown) page with its custom tag, it might not work until you restart the dev server.
 
@@ -22,11 +22,11 @@ This chapter describes how to setup a local environment to be able to build the
 
 ### Linux / MacOS
 
-The following has been tested on Linux and MacOS (Windows seems to have a few minors that prevent the script to run completely). 
+The following has been tested on Linux and MacOS (Windows seems to have a few minors that prevent the script to run completely).
 
 #### Ruby 2.4.3
 
-It is highly recommended to use the [Ruby Version Manager (RVM)](https://rvm.io). 
+It is highly recommended to use the [Ruby Version Manager (RVM)](https://rvm.io).
 Once installed it will help to automatically download and configure `Ruby`:
 
 ```bash
@@ -45,7 +45,10 @@ Continuing with compilation.
 # ...
 ```
 
-As version 2.4.3 requires the an older (deprecated) version of [OpenSSL](https://www.openssl.org) it is possible that the compilation from source fails on the recent distribution (as they no longer provide the required version):
+<details>
+  <summary>Solve ruby build problem(s) on Linux</summary>
+
+As version 2.4.3 requires the an older (deprecated) version of [OpenSSL](https://www.openssl.org) it is possible that the compilation from source fails on the recent distribution (as they no longer provide the required version).
 
 ```bash
 $ rvm install "ruby-2.4.3"
@@ -65,7 +68,7 @@ Error running '__rvm_make -j8',
 please read /home/foo/.rvm/log/1709118815_ruby-2.4.3/make.log
 ```
 
-Modern distributions do not provide the required OpenSSL Version 1.1.1 dependency anymore. 
+Modern distributions do not provide the required OpenSSL Version 1.1.1 dependency anymore.
 Check the logs:
 
 ```log
@@ -101,16 +104,33 @@ You should now be able to use `rvm` to build using the following parameters:
 rvm install "ruby-2.4.3" -C --with-openssl-dir=/opt/openssl-1.1.1q
 ```
 
+</details>
+
 ## Running in development mode
 
 To run the website on your local machine on a development server with live reload:
 
 - run the released (stable) version of the documentation execute `npm run build-local-stable -y`
 - run the latest (work in progress) version use `npm run build-local-latest -y`
 
-As the compilation can take a few minutes due to the size of the docs, wait for the "VuePress dev server listening at http://localhost:8080 (or another available port)" message.
+As the compilation can take a few minutes due to the size of the docs, wait for the "VuePress dev server listening at <http://localhost:8080> (or another available port)" message.
 When loading the website in the browser it may take a few seconds until it finally appears.
 
+### Build documentation from PR
+
+In special situations; e.g. if you make changes in the documentation repository that might impact the website build, it is possible to build the website from a PR.
+This makes it possible to verify that your proposed changes do not have negative side effects:
+
+```bash
+ARGUMENTS="--pull-request 2272" npm run build-local
+```
+
+Available ARGUMENTS:
+
+- `--verbose`
+- `--no-clone`
+- `--pull-request #`
+
 ## Building the final website
 
 This step is normally done by a CI service (e.g. Netlify).

add-blog-meta.rb

@@ -1,7 +1,7 @@
 # Adds the OpenGraph & Twitter meta tags to the blog articles
 require "fileutils"
 
-puts ">>> Adding meta-data to blog posts"
+puts "➡️ Adding meta-data to blog posts"
 
 Dir.glob("blog/*.md").each { |file|
     next if file =~ /index\.md/
@@ -18,7 +18,7 @@
     FileUtils.mkdir_p('.vuepress/tmp')
     FileUtils.mv(file, ".vuepress/tmp/#{File.basename(file)}")
 
-    puts " -> #{file}"
+    puts "   ➡️ #{file}"
     File.open(file, 'w+') { |out|
         File.open(".vuepress/tmp/#{File.basename(file)}").each { |line|
 

generate_iconset_doc.rb

@@ -69,9 +69,9 @@
     f.puts "<IconsetDisplay icons=\"#{$icons_list.join(',')}\"/>"
 }
 
-puts " -> File written in #{$out_dir}/#{$iconset_name}/readme.md"
+puts "   ➡️ File written in #{$out_dir}/#{$iconset_name}/readme.md"
 
 # FileUtils.mkdir_p(".vuepress/public/iconsets")
 FileUtils.cp_r("#{$original_iconsets_location}/#{$iconset_name}/src/main/resources/icons", ".vuepress/public/iconsets/#{$iconset_name}")
 
-puts " -> Icons copied to .vuepress/public/iconsets/#{$iconset_name}"
+puts "   ➡️ Icons copied to .vuepress/public/iconsets/#{$iconset_name}"

package.json

@@ -28,11 +28,12 @@
   "scripts": {
     "predev": "npm install && npx update-browserslist-db@latest",
     "dev": "npx vuepress dev",
-    "prepare-docs": "ruby prepare-docs.rb",
+    "prepare-docs": "ruby prepare-docs.rb $ARGUMENTS",
     "add-blog-meta": "ruby add-blog-meta.rb",
     "build": "ruby prepare-docs.rb && ruby add-blog-meta.rb && vuepress build .",
     "build-only": "vuepress build .",
-    "build-local": "rm -f javadoc-*.tgz* && npm run prepare-docs && npm run dev",
+    "prebuild-local": "npm run prepare-docs",
+    "build-local": "npm run dev --silent",
     "build-local-latest": "OH_DOCS_VERSION=final npm run build-local",
     "build-local-stable": "OH_DOCS_VERSION=final-stable npm run build-local"
   },