diff --git a/.gitignore b/.gitignore index b2a6dd91..7f530039 100644 --- a/.gitignore +++ b/.gitignore @@ -66,6 +66,3 @@ typings/ # VuePress dist vuepress - -# openhab-docs in .vuepress -.vuepress/openhab-docs diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 00000000..19c7bdba --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +16 \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index ff30c446..2a1c4f96 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,3 +1,7 @@ { - "editor.tabSize": 2 + "editor.tabSize": 2, + "editor.formatOnSave": true, + "[ruby]": { + "editor.defaultFormatter": "testdouble.vscode-standard-ruby" + } } \ No newline at end of file diff --git a/.vuepress/.gitignore b/.vuepress/.gitignore index 705ee59b..6ef0ad12 100644 --- a/.vuepress/.gitignore +++ b/.vuepress/.gitignore @@ -2,3 +2,4 @@ addons-* public/logos thing-types.json tmp +openhab-docs diff --git a/.vuepress/config.js b/.vuepress/config.js index 15660eef..fc953612 100644 --- a/.vuepress/config.js +++ b/.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', diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb32cc11..343459f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ 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. @@ -10,9 +10,9 @@ If you are using a Ruby version manager like [rvm](https://rvm.io/), running `rv ## 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): +
+ Solve ruby build problem(s) on Linux + +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,6 +104,8 @@ 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 ``` +
+ ## Running in development mode To run the website on your local machine on a development server with live reload: @@ -108,9 +113,24 @@ To run the website on your local machine on a development server with live reloa - 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 (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). diff --git a/add-blog-meta.rb b/add-blog-meta.rb index f77cbd2b..d9dac472 100644 --- a/add-blog-meta.rb +++ b/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| diff --git a/generate_iconset_doc.rb b/generate_iconset_doc.rb index ac4c8045..36db015d 100644 --- a/generate_iconset_doc.rb +++ b/generate_iconset_doc.rb @@ -69,9 +69,9 @@ f.puts "" } -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}" diff --git a/package-lock.json b/package-lock.json index 1403878a..bba4e361 100644 --- a/package-lock.json +++ b/package-lock.json @@ -27828,4 +27828,4 @@ "dev": true } } -} +} \ No newline at end of file diff --git a/package.json b/package.json index d5004053..d1325385 100644 --- a/package.json +++ b/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" }, diff --git a/prepare-docs.rb b/prepare-docs.rb index ca0fb8dd..31357392 100644 --- a/prepare-docs.rb +++ b/prepare-docs.rb @@ -5,30 +5,92 @@ require "net/http" require "uri" require "rexml/document" -# require "nokogiri" +require 'json' +require 'open-uri' $docs_repo = "https://github.com/openhab/openhab-docs" $docs_repo_root = $docs_repo + "/blob/main" $docs_repo_branch = "final" $addons_repo_branch = "main" -$version = nil +$version = 'final' +$verbose = false $ignore_addons = ['transport.modbus', 'transport.feed', 'javasound', 'webaudio', 'oh2'] +def verbose(message) + if ($verbose == true) then + puts message + end +end + +def checkout_pull_request(pr, target_directory) + pull_request_url = "https://api.github.com/repos/openhab/openhab-docs/pulls/#{pr}" + + response = JSON.parse(open(pull_request_url).read) + repository_url = response['head']['repo']['clone_url'] + label = response['head']['label'] + sha = response['head']['sha'] + branch = response['head']['ref'] + title = response['title'] + + puts "➡️ Cloning repository 📦 #{label} ..." + puts " ↪️ PR ##{pr}: #{title}" + + system("OH_DOCS_VERSION=#{branch}") + + FileUtils.cd(target_directory, verbose: false) do + system("git clone --depth 1 #{repository_url} --branch #{branch} #{$verbose ? '' : '--quiet'}") + system("git reset ##{sha} #{$verbose ? '' : '--quiet'}") + end + end + +verbose "🧹 Cleaning existing documentation downloads ..." +Dir.glob("javadoc-*.tgz*").select { |file| /pattern/.match file }.each { |file| File.delete(file) } + +$parameter_no_clone = false +$pull_request = nil + +previous_argument = ""; +ARGV.each do |arg| + case arg + when "--no-clone" + $parameter_no_clone = true + verbose " --no-clone ➡️ existing clone will be used" + when "--verbose" + $verbose = true + else + case previous_argument + when "--pull-request" + $pull_request = arg + $version = "final" + verbose "➡️ PR #{$pull_request} will be used to build documentation" + end + end + previous_argument = arg +end + + if ENV["OH_DOCS_VERSION"] then - puts ">>> Generating docs for version #{ENV["OH_DOCS_VERSION"]}" $version = ENV["OH_DOCS_VERSION"] $version += ".0" if $version.split(".").length == 2 end -if (ARGV[0] && ARGV[0] == "--no-clone" && Dir.exists?(".vuepress/openhab-docs")) then - puts ">>> Re-using existing clone" +puts "➡️ Generating docs for version #{$version}" + + +if ($parameter_no_clone && Dir.exists?(".vuepress/openhab-docs")) then + puts "➡️ Re-using existing clone" else - puts ">>> Deleting .vuepress/openhab-docs if existing..." + verbose "➡️ Deleting .vuepress/openhab-docs if existing..." FileUtils.rm_rf(".vuepress/openhab-docs") +end - puts ">>> Cloning openhab-docs" - `git clone --depth 1 --branch #{$version ? $version : $docs_repo_branch} https://github.com/openhab/openhab-docs .vuepress/openhab-docs` +if ($pull_request) then + # .vuepress/openhab-docs is git-ignored in the website repository, which is why we can clone it into website without any issue. + checkout_pull_request($pull_request, '.vuepress') +elsif (!$parameter_no_clone) + puts "➡️ Cloning repository #{$docs_repo} 📦 ..." + `git clone --depth 1 --branch #{$version ? $version : $docs_repo_branch} #{$docs_repo} .vuepress/openhab-docs` end # Get a list of sub-addons to transform them into links @@ -36,7 +98,7 @@ def get_subs_links(parent_addon_id, search_dir) sub_addons = [] Dir.glob("#{search_dir}/#{parent_addon_id}.*/**/readme.md").each { |sub_readme| sub_addon_id = File.dirname(sub_readme).split('/').last - puts " -> expanding list of sub-addons: #{sub_addon_id}" + verbose " ➡️ expanding list of sub-addons: #{sub_addon_id}" File.open(sub_readme).each { |line| if line =~ /^# / then sub_addons.push([sub_addon_id, line.gsub('# ', '').strip]) @@ -59,7 +121,7 @@ def process_file(indir, file, outdir, source) og_description = 'a vendor and technology agnostic open source automation software for your home' if !File.exists?("#{indir}/#{file}") then - puts "process_file: IGNORING (NON-EXISTING): #{indir}/#{file}" + verbose "process_file: IGNORING (NON-EXISTING): #{indir}/#{file}" return end @@ -282,60 +344,59 @@ def process_file(indir, file, outdir, source) } end -puts ">>> Migrating the introduction article" +puts "➡️ Migrating the introduction article" process_file(".vuepress/openhab-docs", "introduction.md", "docs", "https://github.com/openhab/openhab-docs/blob/main/introduction.md") FileUtils.mv("docs/introduction.md", "docs/readme.md") -puts ">>> Migrating common images" +puts "➡️ Migrating common images" FileUtils.mkdir_p("docs/images") FileUtils.cp_r(".vuepress/openhab-docs/images/distro.png", "docs/images") FileUtils.cp_r(".vuepress/openhab-docs/images/dashboard.png", "docs/images") -puts ">>> Migrating logos" +puts "➡️ Migrating logos" FileUtils.cp_r(".vuepress/openhab-docs/images/addons", ".vuepress/public/logos") -puts ">>> Migrating the Concepts section" +puts "➡️ Migrating the Concepts section" Dir.glob(".vuepress/openhab-docs/concepts/*.md").each { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/concepts", file, "docs/concepts", "#{$docs_repo_root}/concepts/#{file}") } -puts " -> images and diagrams" +verbose " ➡️ images and diagrams" FileUtils.cp_r(".vuepress/openhab-docs/concepts/images", "docs/concepts") FileUtils.cp_r(".vuepress/openhab-docs/concepts/diagrams", "docs/concepts") - -puts ">>> Migrating the Installation section" +puts "➡️ Migrating the Installation section" Dir.glob(".vuepress/openhab-docs/installation/*.md") { |path| file = File.basename(path) next if file == "designer.md" - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/installation", file, "docs/installation", "#{$docs_repo_root}/installation/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/installation/images", "docs/installation") -puts ">>> Migrating the Tutorial section" +puts "➡️ Migrating the Tutorial section" Dir.glob(".vuepress/openhab-docs/tutorials/getting_started/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/tutorials/getting_started", file, "docs/tutorial", "#{$docs_repo_root}/tutorials/getting_started/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/tutorials/getting_started/images", "docs/tutorial") -puts ">>> Migrating the Configuration section" +puts "➡️ Migrating the Configuration section" Dir.glob(".vuepress/openhab-docs/configuration/*.md") { |path| file = File.basename(path) next if file == "transform.md" # Useless, copy the one from addons - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/configuration", file, "docs/configuration", "#{$docs_repo_root}/configuration/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/configuration/images", "docs/configuration") # TODO: Remove for the 4.2.0 release @@ -344,354 +405,363 @@ def process_file(indir, file, outdir, source) process_file(".vuepress/openhab-docs/addons", "transformations.md", "docs/configuration", "#{$docs_repo_root}/addons/transformations.md") end -# TODO: Remove the if statement and the content of else for the 4.2.0 release +# TODO: Remove the if statement and the content of if for the 4.2.0 release # Additional files and images for the latest docs -if $version == "final" then - - puts ">>> Migrating the Main UI section" +if $version == "final-stable" then + # Additional files and images for the stable docs + puts "➡️ Migrating the Settings section" + Dir.glob(".vuepress/openhab-docs/settings/*.md") { |path| + file = File.basename(path) + verbose " ➡️ #{file}" + process_file(".vuepress/openhab-docs/settings", file, "docs/settings", "#{$docs_repo_root}/settings/#{file}") + } + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/settings/images", "docs/settings/images") +else + puts "➡️ Migrating the Main UI section" Dir.glob(".vuepress/openhab-docs/mainui/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/mainui", file, "docs/mainui", "#{$docs_repo_root}/mainui/#{file}") } ["developer", "settings"].each { |subsection| Dir.glob(".vuepress/openhab-docs/mainui/#{subsection}/*.md") { |path| file = File.basename(path) - puts " -> #{subsection}/#{file}" + verbose " ➡️ #{subsection}/#{file}" process_file(".vuepress/openhab-docs/mainui/#{subsection}", file, "docs/mainui/#{subsection}", "#{$docs_repo_root}/mainui/#{subsection}/#{file}") } } - puts " -> images" + verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/mainui/images", "docs/mainui") - -else -# Additional files and images for the stable docs - puts ">>> Migrating the Settings section" - Dir.glob(".vuepress/openhab-docs/settings/*.md") { |path| - file = File.basename(path) - puts " -> #{file}" - process_file(".vuepress/openhab-docs/settings", file, "docs/settings", "#{$docs_repo_root}/settings/#{file}") - } - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/settings/images", "docs/settings/images") - end -puts ">>> Migrating the Migration Tutorial section" +puts "➡️ Migrating the Migration Tutorial section" Dir.glob(".vuepress/openhab-docs/configuration/migration/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/configuration/migration", file, "docs/configuration/migration", "#{$docs_repo_root}/configuration/migration/#{file}") } -puts " -> images" +verbose " ➡️ images" #FileUtils.cp_r(".vuepress/openhab-docs/configuration/migration/images", "docs/configuration/migration/") // no images placed yet -puts ">>> Migrating the Blockly Tutorial section" +puts "➡️ Migrating the Blockly Tutorial section" Dir.glob(".vuepress/openhab-docs/configuration/blockly/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/configuration/blockly", file, "docs/configuration/blockly", "#{$docs_repo_root}/configuration/blockly/#{file}") } -puts " -> images" +verbose " ➡️ images" #FileUtils.cp_r(".vuepress/openhab-docs/configuration/blockly/images", "docs/configuration/blockly/") // no images placed yet -puts ">>> Migrating the UI section" +puts "➡️ Migrating the UI section" Dir.glob(".vuepress/openhab-docs/ui/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/ui", file, "docs/ui", "#{$docs_repo_root}/ui/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/ui/images", "docs/ui") -puts " -> habpanel" +verbose " ➡️ habpanel" FileUtils.mkdir_p("docs/ui/habpanel") process_file(".vuepress/openhab-docs/_addons_uis/habpanel/doc", "habpanel.md", "docs/ui/habpanel", "") -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/_addons_uis/habpanel/doc/images", "docs/ui/habpanel") if Dir.exists?(".vuepress/openhab-docs/_addons_uis/habpanel/doc/images") -puts " -> habot" +verbose " ➡️ habot" FileUtils.mkdir_p("docs/ui/habot") process_file(".vuepress/openhab-docs/_addons_uis/habot", "readme.md", "docs/ui/habot", "") -puts " -> images" +verbose " ➡️ images" -puts " -> components" +verbose " ➡️ components" FileUtils.mkdir_p("docs/ui/components") Dir.glob(".vuepress/openhab-docs/_addons_uis/org.openhab.ui/doc/components/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/_addons_uis/org.openhab.ui/doc/components", file, "docs/ui/components", "https://github.com/openhab/openhab-webui/blob/main/bundles/org.openhab.ui/doc/components/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/_addons_uis/org.openhab.ui/doc/components/images", "docs/ui/components") if Dir.exists?(".vuepress/openhab-docs/_addons_uis/org.openhab.ui/doc/components/images") -puts ">>> Migrating the Apps section" +puts "➡️ Migrating the Apps section" Dir.glob(".vuepress/openhab-docs/addons/uis/apps/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/addons/uis/apps", file, "docs/apps", "#{$docs_repo_root}/addons/uis/apps/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/addons/uis/apps/images", "docs/apps") -puts ">>> Migrating the Administration section" +puts "➡️ Migrating the Administration section" Dir.glob(".vuepress/openhab-docs/administration/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/administration", file, "docs/administration", "#{$docs_repo_root}/administration/#{file}") } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/administration/images", "docs/administration") -puts ">>> Migrating the Developer section" +puts "➡️ Migrating the Developer section" Dir.glob(".vuepress/openhab-docs/developers/*.md") { |path| file = File.basename(path) - puts " -> #{file}" + verbose " ➡️ #{file}" process_file(".vuepress/openhab-docs/developers", file, "docs/developer", "#{$docs_repo_root}/developer/#{file}") } ["audio", "bindings", "ioservices", "legacy", "module-types", "osgi", "persistence", "transformations", "utils", "ide"].each { |subsection| Dir.glob(".vuepress/openhab-docs/developers/#{subsection}/*.md") { |path| file = File.basename(path) - puts " -> #{subsection}/#{file}" + verbose " ➡️ #{subsection}/#{file}" process_file(".vuepress/openhab-docs/developers/#{subsection}", file, "docs/developer/#{subsection}", "#{$docs_repo_root}/developer/#{subsection}/#{file}") } } -puts " -> images" +verbose " ➡️ images" FileUtils.cp_r(".vuepress/openhab-docs/developers/bindings/images", "docs/developer/bindings") FileUtils.cp_r(".vuepress/openhab-docs/developers/osgi/images", "docs/developer/osgi") FileUtils.cp_r(".vuepress/openhab-docs/developers/ide/images", "docs/developer/ide") -# Additional files and images for the latest docs -#if $version == "final" then - - #puts "-> Add additional sections only to the 'latest' docs." - - ["addons"].each { |subsection| - Dir.glob(".vuepress/openhab-docs/developers/#{subsection}/*.md") { |path| - file = File.basename(path) - puts " --> #{subsection}/#{file}" - process_file(".vuepress/openhab-docs/developers/#{subsection}", file, "docs/developer/#{subsection}", "#{$docs_repo_root}/developer/#{subsection}/#{file}") - } +["addons"].each { |subsection| + Dir.glob(".vuepress/openhab-docs/developers/#{subsection}/*.md") { |path| + file = File.basename(path) + verbose " ➡️ #{subsection}/#{file}" + process_file(".vuepress/openhab-docs/developers/#{subsection}", file, "docs/developer/#{subsection}", "#{$docs_repo_root}/developer/#{subsection}/#{file}") } - -#else - -# puts "-> Skipping additional doc parts that are not yet available in stable." - -#end - -### ADDONS - -puts ">>> Migrating add-ons: Automation" -Dir.glob(".vuepress/openhab-docs/_addons_automation/**") { |path| - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" - FileUtils.mkdir_p("addons/automation/" + addon) - process_file(".vuepress/openhab-docs/_addons_automation", addon + "/readme.md", "addons/automation", nil) - - if (Dir.exists?(".vuepress/openhab-docs/_addons_automation/#{addon}/doc")) then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_automation/#{addon}/doc", "addons/automation/#{addon}") - end - -} - - -puts ">>> Migrating add-ons: Persistence" -Dir.glob(".vuepress/openhab-docs/_addons_persistences/**") { |path| - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" - FileUtils.mkdir_p("addons/persistence/" + addon) - process_file(".vuepress/openhab-docs/_addons_persistences", addon + "/readme.md", "addons/persistence", nil) - - if (Dir.exists?(".vuepress/openhab-docs/_addons_persistences/#{addon}/doc")) then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_persistences/#{addon}/doc", "addons/persistence/#{addon}") - end } -puts ">>> Migrating add-ons: Transformations" -Dir.glob(".vuepress/openhab-docs/_addons_transformations/**") { |path| - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" - FileUtils.mkdir_p("addons/transformations/" + addon) - process_file(".vuepress/openhab-docs/_addons_transformations", addon + "/readme.md", "addons/transformations", nil) -} - +### ADDONS -puts ">>> Migrating add-ons: Voice" -Dir.glob(".vuepress/openhab-docs/_addons_voices/**") { |path| - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" - FileUtils.mkdir_p("addons/voice/" + addon) - process_file(".vuepress/openhab-docs/_addons_voices", addon + "/readme.md", "addons/voice", nil) -} +# External content is not included for PRs - therefore the _addons_*** folders are not present for PR checks - this section will be skipped. +if $pull_request then + puts "" + puts "⚠️ Add-on documentation depends on Jenkins job - will be skipped ..." + puts "" +else + puts "➡️ Migrating add-ons: Automation" + Dir.glob(".vuepress/openhab-docs/_addons_automation/**") { |path| + addon = File.basename(path) + next if $ignore_addons.include?(addon) + verbose " ➡️ #{addon}" + FileUtils.mkdir_p("addons/automation/" + addon) + process_file(".vuepress/openhab-docs/_addons_automation", addon + "/readme.md", "addons/automation", nil) + + if (Dir.exists?(".vuepress/openhab-docs/_addons_automation/#{addon}/doc")) then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_automation/#{addon}/doc", "addons/automation/#{addon}") + end + } -puts ">>> Migrating add-ons: IO" -Dir.glob(".vuepress/openhab-docs/_addons_ios/**") { |path| - # See below for the Alexa & Mycroft special cases - next if path =~ /alexa-skill/ - next if path =~ /mycroft-skill/ - next if path =~ /google-assistant/ - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" - - # Detect and skip 1.x bindings - shouldn't ultimately occur - if addon =~ /1$/ then - puts " (1.x, skipping)" - next - end + puts "➡️ Migrating add-ons: Persistence" + Dir.glob(".vuepress/openhab-docs/_addons_persistences/**") { |path| + addon = File.basename(path) + next if $ignore_addons.include?(addon) + verbose " ➡️ #{addon}" + FileUtils.mkdir_p("addons/persistence/" + addon) + process_file(".vuepress/openhab-docs/_addons_persistences", addon + "/readme.md", "addons/persistence", nil) - FileUtils.mkdir_p("addons/integrations/" + addon) - process_file(".vuepress/openhab-docs/_addons_ios", addon + "/readme.md", "addons/integrations", nil) - if (Dir.exists?(".vuepress/openhab-docs/_addons_ios/#{addon}/doc")) then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/#{addon}/doc", "addons/integrations/#{addon}") - end - if (Dir.exists?(".vuepress/openhab-docs/_addons_ios/#{addon}/contrib")) then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/#{addon}/contrib", "addons/integrations/#{addon}") - end -} + if (Dir.exists?(".vuepress/openhab-docs/_addons_persistences/#{addon}/doc")) then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_persistences/#{addon}/doc", "addons/persistence/#{addon}") + end + } -puts ">>> Migrating add-ons: UI" -Dir.glob(".vuepress/openhab-docs/_addons_uis/**") { |path| - next if path =~ /org.openhab.ui/ - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" - FileUtils.mkdir_p("addons/ui/" + addon) - process_file(".vuepress/openhab-docs/_addons_uis", addon + "/readme.md", "addons/ui", nil) - - if (Dir.exists?(".vuepress/openhab-docs/_addons_uis/#{addon}/doc")) then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_uis/#{addon}/doc", "addons/ui/#{addon}") - end -} + puts "➡️ Migrating add-ons: Transformations" + Dir.glob(".vuepress/openhab-docs/_addons_transformations/**") { |path| + addon = File.basename(path) + next if $ignore_addons.include?(addon) + verbose " ➡️ #{addon}" + FileUtils.mkdir_p("addons/transformations/" + addon) + process_file(".vuepress/openhab-docs/_addons_transformations", addon + "/readme.md", "addons/transformations", nil) + } -# Handle those three separately - copy them in the "ecosystem" section -puts ">>> Migrating special ecosystem add-ons" -puts " -> Create folders" -FileUtils.mkdir_p("docs/ecosystem/alexa") -FileUtils.mkdir_p("docs/ecosystem/mycroft") -FileUtils.mkdir_p("docs/ecosystem/google-assistant") -puts " -> Process alexa-skill docs" -process_file(".vuepress/openhab-docs/_addons_ios/alexa-skill", "readme.md", "docs/ecosystem/alexa", "https://github.com/openhab/openhab-alexa/blob/master/USAGE.md") -puts " -> images" -FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/alexa-skill/images", "docs/ecosystem/alexa") + puts "➡️ Migrating add-ons: Voice" + Dir.glob(".vuepress/openhab-docs/_addons_voices/**") { |path| + addon = File.basename(path) + next if $ignore_addons.include?(addon) + verbose " ➡️ #{addon}" + FileUtils.mkdir_p("addons/voice/" + addon) + process_file(".vuepress/openhab-docs/_addons_voices", addon + "/readme.md", "addons/voice", nil) + } -puts " -> Process mycroft-skill docs" -process_file(".vuepress/openhab-docs/_addons_ios/mycroft-skill", "readme.md", "docs/ecosystem/mycroft", "https://github.com/openhab/openhab-mycroft/blob/master/USAGE.md") -puts " -> Process google-assistant docs" -process_file(".vuepress/openhab-docs/_addons_ios/google-assistant", "readme.md", "docs/ecosystem/google-assistant", "https://github.com/openhab/openhab-google-assistant/blob/master/docs/USAGE.md") -puts " -> images" -FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/google-assistant/images", "docs/ecosystem/google-assistant") + puts "➡️ Migrating add-ons: IO" + Dir.glob(".vuepress/openhab-docs/_addons_ios/**") { |path| + # See below for the Alexa & Mycroft & Google Assistant special cases + next if path =~ /alexa-skill/ + next if path =~ /mycroft-skill/ + next if path =~ /google-assistant/ + addon = File.basename(path) + next if $ignore_addons.include?(addon) + verbose " ➡️ #{addon}" + + # Detect and skip 1.x bindings - shouldn't ultimately occur + if addon =~ /1$/ then + puts " (1.x, skipping)" + next + end + + FileUtils.mkdir_p("addons/integrations/" + addon) + process_file(".vuepress/openhab-docs/_addons_ios", addon + "/readme.md", "addons/integrations", nil) + if (Dir.exists?(".vuepress/openhab-docs/_addons_ios/#{addon}/doc")) then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/#{addon}/doc", "addons/integrations/#{addon}") + end + if (Dir.exists?(".vuepress/openhab-docs/_addons_ios/#{addon}/contrib")) then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/#{addon}/contrib", "addons/integrations/#{addon}") + end + } + puts "➡️ Migrating add-ons: UI" + Dir.glob(".vuepress/openhab-docs/_addons_uis/**") { |path| + next if path =~ /org.openhab.ui/ + addon = File.basename(path) + next if $ignore_addons.include?(addon) + verbose " ➡️ #{addon}" + FileUtils.mkdir_p("addons/ui/" + addon) + process_file(".vuepress/openhab-docs/_addons_uis", addon + "/readme.md", "addons/ui", nil) + + if (Dir.exists?(".vuepress/openhab-docs/_addons_uis/#{addon}/doc")) then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_uis/#{addon}/doc", "addons/ui/#{addon}") + end + } -puts ">>> Migrating add-ons: Bindings" -Dir.glob(".vuepress/openhab-docs/_addons_bindings/**") { |path| - addon = File.basename(path) - next if $ignore_addons.include?(addon) - puts " -> #{addon}" + # Handle those three separately - copy them in the "ecosystem" section + puts "➡️ Migrating special ecosystem add-ons" + verbose " ➡️Create folders" + FileUtils.mkdir_p("docs/ecosystem/alexa") + FileUtils.mkdir_p("docs/ecosystem/mycroft") + FileUtils.mkdir_p("docs/ecosystem/google-assistant") + + verbose " ➡️Process alexa-skill docs" + process_file(".vuepress/openhab-docs/_addons_ios/alexa-skill", "readme.md", "docs/ecosystem/alexa", "https://github.com/openhab/openhab-alexa/blob/master/USAGE.md") + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/alexa-skill/images", "docs/ecosystem/alexa") + + verbose " ➡️Process mycroft-skill docs" + process_file(".vuepress/openhab-docs/_addons_ios/mycroft-skill", "readme.md", "docs/ecosystem/mycroft", "https://github.com/openhab/openhab-mycroft/blob/master/USAGE.md") + + verbose " ➡️Process google-assistant docs" + process_file(".vuepress/openhab-docs/_addons_ios/google-assistant", "readme.md", "docs/ecosystem/google-assistant", "https://github.com/openhab/openhab-google-assistant/blob/master/docs/USAGE.md") + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_ios/google-assistant/images", "docs/ecosystem/google-assistant") + + + puts "➡️ Migrating add-ons: Bindings" + Dir.glob(".vuepress/openhab-docs/_addons_bindings/**") { |path| + addon = File.basename(path) + next if $ignore_addons.include?(addon) + + verbose " ➡️ #{addon}" + + # Detect and skip 1.x bindings - shouldn't ultimately occur + if addon =~ /1$/ then + puts " (1.x, skipping)" + next + end + + FileUtils.mkdir_p("addons/bindings/" + addon) + process_file(".vuepress/openhab-docs/_addons_bindings", addon + "/readme.md", "addons/bindings", nil) + if (Dir.exists?(".vuepress/openhab-docs/_addons_bindings/#{addon}/doc") && addon != "zwave") then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_bindings/#{addon}/doc", "addons/bindings/#{addon}") + elsif (Dir.exists?(".vuepress/openhab-docs/_addons_bindings/#{addon}/contrib") && addon != "zwave") then + verbose " ➡️ images" + FileUtils.cp_r(".vuepress/openhab-docs/_addons_bindings/#{addon}/contrib", "addons/bindings/#{addon}") + elsif addon == "zwave" then + verbose " ➡️ things.md" + FileUtils.mkdir_p("addons/bindings/zwave/doc") + process_file(".vuepress/openhab-docs/_addons_bindings", "zwave/doc/things.md", "addons/bindings", nil) + end + } - # Detect and skip 1.x bindings - shouldn't ultimately occur - if addon =~ /1$/ then - puts " (1.x, skipping)" - next - end - FileUtils.mkdir_p("addons/bindings/" + addon) - process_file(".vuepress/openhab-docs/_addons_bindings", addon + "/readme.md", "addons/bindings", nil) - if (Dir.exists?(".vuepress/openhab-docs/_addons_bindings/#{addon}/doc") && addon != "zwave") then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_bindings/#{addon}/doc", "addons/bindings/#{addon}") - elsif (Dir.exists?(".vuepress/openhab-docs/_addons_bindings/#{addon}/contrib") && addon != "zwave") then - puts " -> images" - FileUtils.cp_r(".vuepress/openhab-docs/_addons_bindings/#{addon}/contrib", "addons/bindings/#{addon}") - elsif addon == "zwave" then - puts " -> things.md" - FileUtils.mkdir_p("addons/bindings/zwave/doc") - process_file(".vuepress/openhab-docs/_addons_bindings", "zwave/doc/things.md", "addons/bindings", nil) + puts "➡️ Creating Z-Wave thing viewer" + if (File.exists?('.vuepress/openhab-docs/_addons_bindings/zwave/doc/things.md')) then + File.open('addons/bindings/zwave/thing.md', 'w+') { |out| + out.puts '---' + out.puts 'title: ZWave Thing' + out.puts 'prev: ./' + out.puts '---' + out.puts + out.puts '' + } end -} - - -puts ">>> Creating ZWave thing viewer" -if (File.exists?('.vuepress/openhab-docs/_addons_bindings/zwave/doc/things.md')) then - File.open('addons/bindings/zwave/thing.md', 'w+') { |out| - out.puts '---' - out.puts 'title: ZWave Thing' - out.puts 'prev: ./' - out.puts '---' - out.puts - out.puts '' - } + # puts "➡️ Migrating Z-Wave docs" + # Dir.glob(".vuepress/openhab-docs/_addons_bindings/zwave/doc/*.md") { |path| + # next if path =~ /device\.md/ + # file = File.basename(path) + # puts " -> #{file}" + # FileUtils.mkdir_p("addons/bindings/zwave/doc") + # process_file(".vuepress/openhab-docs/_addons_bindings/zwave/doc", file, "addons/bindings/zwave/doc", nil) + # } end -# puts ">>> Migrating Z-Wave docs" -# Dir.glob(".vuepress/openhab-docs/_addons_bindings/zwave/doc/*.md") { |path| -# next if path =~ /device\.md/ -# file = File.basename(path) -# puts " -> #{file}" -# FileUtils.mkdir_p("addons/bindings/zwave/doc") -# process_file(".vuepress/openhab-docs/_addons_bindings/zwave/doc", file, "addons/bindings/zwave/doc", nil) -# } - - # Write arrays of addons by type to include in VuePress config.js -puts ">>> Writing add-ons arrays to files for sidebar navigation" +puts "➡️ Writing add-ons arrays to files for sidebar navigation" ["bindings", "persistence", "automation", "integrations", "transformations", "voice", "ui"].each { |type| File.open(".vuepress/addons-#{type}.js", "w+") { |file| file.puts "module.exports = [" - Dir.foreach('addons/' + type) { |dir| - if !dir.include?('.') then - # puts dir - - File.readlines('addons/' + type + '/' + dir + '/readme.md').each { |line| - if line =~ /^label:/ then - title = line.gsub("label: ", "").gsub("\n", "") - file.puts "\t['#{type}/#{dir}/', '#{title}']," if !(title =~ /1\.x/) - end - } - end - } + if (Dir.exists?('addons/' + type)) + Dir.foreach('addons/' + type) { |dir| + if !dir.include?('.') then + # puts dir + File.readlines('addons/' + type + '/' + dir + '/readme.md').each { |line| + if line =~ /^label:/ then + title = line.gsub("label: ", "").gsub("\n", "") + file.puts "\t['#{type}/#{dir}/', '#{title}']," if !(title =~ /1\.x/) + end + } + end + } + end file.puts "]" } } -# Regenerate the classic iconset docs -puts ">>> Generating iconset" -system("ruby generate_iconset_doc.rb .vuepress/openhab-docs/_addons_iconsets classic .vuepress/openhab-docs/_data docs/configuration/iconsets") +# External content is not included for PRs - therefore the _addons_iconsets folder is not present for PR checks - this section will be skipped. +if $pull_request then + puts "" + puts "⚠️ Iconsets depend on Jenkins job - will be skipped ..." + puts "" +else + # Regenerate the classic iconset docs + puts "➡️ Generating iconset" + system("ruby generate_iconset_doc.rb .vuepress/openhab-docs/_addons_iconsets classic .vuepress/openhab-docs/_data docs/configuration/iconsets") +end # Clean-Ups required for repeated local build -`[ -e javadoc-latest.tar.gz ] && rm javadoc-latest.tar.gz` -`[ -e .vuepress/public/javadoc/latest ] && rm -r .vuepress/public/javadoc/latest` +verbose "🧹 Cleaning existing JavaDoc ..." +FileUtils.rm Dir.glob('javadoc-latest.*'), :force => true +FileUtils.rm Dir.glob('.vuepress/public/javadoc/latest'), :force => true + # Publish latest Javadoc -puts ">>> Downloading and extracting latest Javadoc from Jenkins" +puts "➡️ Downloading and extracting latest Javadoc from Jenkins" `wget -nv https://ci.openhab.org/job/openHAB-JavaDoc/lastSuccessfulBuild/artifact/target/javadoc-latest.tgz` `tar xzvf javadoc-latest.tgz --strip 2 && mv apidocs/ .vuepress/public/javadoc/latest` -# Copy the thing-types.json file to the proper location -FileUtils.cp(".vuepress/openhab-docs/.vuepress/thing-types.json", ".vuepress") +# External content is not included for PRs - therefore thing-types.json is not present for PR checks - this section will be skipped. +if $pull_request then + puts "" + puts "⚠️ Thing types depend on Jenkins job - will be skipped ..." + puts "" +else + # Copy the thing-types.json file to the proper location + puts "➡️ Copying Thing types" + FileUtils.cp(".vuepress/openhab-docs/.vuepress/thing-types.json", ".vuepress") +end