Updated documentation for metoffice to support migration to DataHub API

.devcontainer/devcontainer.json

@@ -8,7 +8,16 @@
       "NODE_VERSION": "18"
     }
   },
-  "appPort": [4000],
+  "forwardPorts": [4000],
+  "portsAttributes": {
+    "4000": {
+      "label": "Documentation preview"
+    },
+    "8124": {
+      "label": "PostCSS",
+      "onAutoForward": "ignore"
+    }
+  },
   "onCreateCommand": "bundle install && npm install",
   "containerEnv": { "DEVCONTAINER": "true" },
   "extensions": [

.gitignore

@@ -4,18 +4,19 @@
 .gist-cache
 .pygments-cache
 public
+source/assets/css/style.css
+source/_data/alerts_data.json
 source/_data/analytics_data.json
 source/_data/blueprint_exchange_data.json
 source/_data/version_data.json
-source/_data/alerts_data.json
 source/_stash
 source/stylesheets/screen.css
 source/.jekyll-cache/
+source/.jekyll-metadata
 vendor
 node_modules
-source/.jekyll-metadata
-*.iml
 .idea/
+*.iml
 .vscode/*
 !.vscode/cSpell.json
 !.vscode/extensions.json

.vscode/tasks.json

@@ -14,10 +14,16 @@
             "label": "Preview",
             "type": "shell",
             "command": "bundle exec rake preview",
+            "options": {
+                "env": {
+                    "NODE_OPTIONS": "--max-old-space-size=8192",
+                },
+            },
             "group": {
                 "kind": "test",
                 "isDefault": true,
             }
+
         }
     ]
 }

Gemfile

@@ -5,18 +5,15 @@ ruby '> 2.5.0'
 group :development do
   gem 'rake', '13.0.6'
   gem 'jekyll', '4.3.2'
-  gem 'compass', '1.0.3'
-  gem 'sass-globbing', '1.1.5'
   gem 'stringex', '2.8.6'
-  # > 2.1.0 causes slowdowns https://github.com/sass/sassc-ruby/issues/189
-  gem 'sassc', '2.1.0'
 end
 
 group :jekyll_plugins do
   gem 'jekyll-paginate', '1.1.0'
   gem 'jekyll-sitemap', '1.4.0'
   gem 'jekyll-commonmark', '1.4.0'
   gem 'jekyll-toc', '0.18.0'
+  gem 'jekyll-postcss', '0.5.0'
 end
 
 gem 'sinatra', '3.0.6'

Gemfile.lock

@@ -3,21 +3,8 @@ GEM
   specs:
     addressable (2.8.4)
       public_suffix (>= 2.0.2, < 6.0)
-    chunky_png (1.4.0)
     colorator (1.1.0)
-    commonmarker (0.23.9)
-    compass (1.0.3)
-      chunky_png (~> 1.2)
-      compass-core (~> 1.0.2)
-      compass-import-once (~> 1.0.5)
-      rb-fsevent (>= 0.9.3)
-      rb-inotify (>= 0.9)
-      sass (>= 3.3.13, < 3.5)
-    compass-core (1.0.3)
-      multi_json (~> 1.0)
-      sass (>= 3.3.0, < 3.5)
-    compass-import-once (1.0.5)
-      sass (>= 3.2, < 3.5)
+    commonmarker (0.23.8)
     concurrent-ruby (1.2.2)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
@@ -27,9 +14,10 @@ GEM
     ffi (1.15.5)
     ffi (1.15.5-x64-mingw32)
     forwardable-extended (2.6.0)
-    google-protobuf (3.23.2)
+    google-protobuf (3.22.2)
+    google-protobuf (3.22.2-x64-mingw32)
     http_parser.rb (0.8.0)
-    i18n (1.14.1)
+    i18n (1.13.0)
       concurrent-ruby (~> 1.0)
     jekyll (4.3.2)
       addressable (~> 2.4)
@@ -50,6 +38,7 @@ GEM
     jekyll-commonmark (1.4.0)
       commonmarker (~> 0.22)
     jekyll-paginate (1.1.0)
+    jekyll-postcss (0.5.0)
     jekyll-sass-converter (3.0.0)
       sass-embedded (~> 1.54)
     jekyll-sitemap (1.4.0)
@@ -68,17 +57,18 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    mini_portile2 (2.8.2)
-    multi_json (1.15.0)
+    mini_portile2 (2.8.1)
     mustermann (3.0.0)
       ruby2_keywords (~> 0.0.1)
-    nokogiri (1.15.2)
-      mini_portile2 (~> 2.8.2)
+    nokogiri (1.14.3)
+      mini_portile2 (~> 2.8.0)
+      racc (~> 1.4)
+    nokogiri (1.14.3-x64-mingw32)
       racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (5.0.1)
-    racc (1.7.0)
+    racc (1.6.2)
     rack (2.2.7)
     rack-protection (3.0.6)
       rack
@@ -87,21 +77,14 @@ GEM
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     rexml (3.2.5)
-    rouge (4.1.2)
+    rouge (4.1.0)
     ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass (3.4.25)
-    sass-embedded (1.63.2)
-      google-protobuf (~> 3.23)
+    sass-embedded (1.62.1)
+      google-protobuf (~> 3.21)
       rake (>= 10.0.0)
-    sass-embedded (1.63.2-x64-mingw32)
-      google-protobuf (~> 3.23)
-    sass-globbing (1.1.5)
-      sass (>= 3.1)
-    sassc (2.1.0)
-      ffi (~> 1.9)
-    sassc (2.1.0-x64-mingw32)
-      ffi (~> 1.9)
+    sass-embedded (1.62.1-x64-mingw32)
+      google-protobuf (~> 3.21)
     sinatra (3.0.6)
       mustermann (~> 3.0)
       rack (~> 2.2, >= 2.2.4)
@@ -123,16 +106,14 @@ PLATFORMS
   x64-mingw32
 
 DEPENDENCIES
-  compass (= 1.0.3)
   jekyll (= 4.3.2)
   jekyll-commonmark (= 1.4.0)
   jekyll-paginate (= 1.1.0)
+  jekyll-postcss (= 0.5.0)
   jekyll-sitemap (= 1.4.0)
   jekyll-toc (= 0.18.0)
-  nokogiri (= 1.15.2)
+  nokogiri (= 1.14.3)
   rake (= 13.0.6)
-  sass-globbing (= 1.1.5)
-  sassc (= 2.1.0)
   sinatra (= 3.0.6)
   stringex (= 2.8.6)
   tzinfo (~> 2.0)

Rakefile

@@ -7,7 +7,6 @@ require 'json'
 ## -- Misc Configs -- ##
 public_dir      = "public/"   # compiled site directory
 source_dir      = "source"    # source file directory
-server_port     = "4000"      # port for preview server eg. localhost:4000
 
 if (/cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
   puts '## Set the codepage to 65001 for Windows machines'
@@ -20,67 +19,69 @@ end
 
 desc "Generate jekyll site"
 task :generate do
-  raise "### You haven't set anything up yet. First run `rake install`." unless File.directory?(source_dir)
-  puts "## Generating Site with Jekyll"
-  success = system "compass compile --css-dir #{source_dir}/stylesheets"
-  abort("Generating CSS failed") unless success
-  success = system "rake analytics_data"
-  abort("Generating analytics data failed") unless success
-  success = system "rake alerts_data"
-  abort("Generating alerts data failed") unless success
-  success = system "rake version_data"
-  abort("Generating version data failed") unless success
-  success = system "rake blueprint_exchange_data"
-  abort("Generating blueprint exchange data failed") unless success
-  success = system "jekyll build"
+  # Hand off this rake task to NPM.
+  # This rake tasks is here as a backward compatible command and still
+  # used by Netlify as long as the old branches are still there.
+  # IT also helps with the muscle memory of developers :)
+  success = system "npm run build"
   abort("Generating site failed") unless success
+
+  # TODO: Needs to move? Maybe generate it dynamically from the source?
   if ENV["CONTEXT"] != 'production'
     File.open("#{public_dir}robots.txt", 'w') do |f|
       f.write "User-agent: *\n"
       f.write "Disallow: /\n"
     end
   end
+
   public_dir
 end
 
 desc "Watch the site and regenerate when it changes"
 task :watch do
-  raise "### You haven't set anything up yet. First run `rake install`." unless File.directory?(source_dir)
-  puts "Starting to watch source with Jekyll and Compass."
-  system "compass compile --css-dir #{source_dir}/stylesheets" unless File.exist?("#{source_dir}/stylesheets/screen.css")
-  jekyllPid = Process.spawn({"OCTOPRESS_ENV"=>"preview"}, "jekyll build --watch --incremental")
-  compassPid = Process.spawn("compass watch")
-
-  trap("INT") {
-    [jekyllPid, compassPid].each { |pid| Process.kill(9, pid) rescue Errno::ESRCH }
-    exit 0
-  }
-
-  [jekyllPid, compassPid].each { |pid| Process.wait(pid) }
+  # Hand off this rake task to NPM.
+  # This rake tasks is here as a backward compatible command and still
+  # used by Netlify as long as the old branches are still there.
+  # IT also helps with the muscle memory of developers :)
+  jekyllPid = Process.spawn("npm run dev")
+  Process.wait(jekyllPid)
 end
 
 desc "preview the site in a web browser"
 task :preview, :listen do |t, args|
-  listen_addr = args[:listen] || '127.0.0.1'
-  listen_addr = '0.0.0.0' unless ENV['DEVCONTAINER'].nil?
-  raise "### You haven't set anything up yet. First run `rake install`." unless File.directory?(source_dir)
-  puts "Starting to watch source with Jekyll and Compass."
-  puts "Now listening on http://localhost:#{server_port}"
-  system "compass compile --css-dir #{source_dir}/stylesheets" unless File.exist?("#{source_dir}/stylesheets/screen.css")
-  system "rake analytics_data"
-  system "rake version_data"
-  system "rake alerts_data"
-  system "rake blueprint_exchange_data"
-  jekyllPid = Process.spawn({"OCTOPRESS_ENV"=>"preview"}, "jekyll build -t --watch --incremental")
-  compassPid = Process.spawn("compass watch")
-  rackupPid = Process.spawn("rackup --port #{server_port} --host #{listen_addr}")
-
-  trap("INT") {
-    [jekyllPid, compassPid, rackupPid].each { |pid| Process.kill(9, pid) rescue Errno::ESRCH }
-    exit 0
-  }
-
-  [jekyllPid, compassPid, rackupPid].each { |pid| Process.wait(pid) }
+  # Hand off this rake task to NPM.
+  # This rake tasks is here as a backward compatible command and still
+  # used by Netlify as long as the old branches are still there.
+  # IT also helps with the muscle memory of developers :)
+
+  # We used to listen/bind to an host address selectively, this might need
+  # to return in the future.
+  # listen_addr = args[:listen] || '127.0.0.1'
+  # listen_addr = '0.0.0.0' unless ENV['DEVCONTAINER'].nil?
+  jekyllPid = Process.spawn("npm run dev")
+  Process.wait(jekyllPid)
+end
+
+desc "Fetch meta data"
+task :fetch_meta_data do
+  puts "## Fetching external meta data..."
+
+  puts "Download data from analytics.home-assistant.io..."
+  success = system "rake analytics_data"
+  abort("Generating analytics data failed") unless success
+
+  puts "Download data from alerts.home-assistant.io..."
+  success = system "rake alerts_data"
+  abort("Generating alerts data failed") unless success
+
+  puts "Download data from version.home-assistant.io..."
+  success = system "rake version_data"
+  abort("Generating version data failed") unless success
+
+  puts "Download data from the blueprint exchange @ community.home-assistant.io..."
+  success = system "rake blueprint_exchange_data"
+  abort("Generating blueprint exchange data failed") unless success
+  puts "Done."
 end
 
 desc "Download data from analytics.home-assistant.io"

_config.yml

@@ -4,6 +4,7 @@
 # ----------------------- #
 
 url: https://www.home-assistant.io
+baseurl: "/"
 title: Home Assistant
 subtitle: Open source home automation that puts local control and privacy first.
 author: Home Assistant
@@ -48,8 +49,12 @@ commonmark:
 highlighter: none
 
 plugins:
+  - jekyll-postcss
   - jekyll-toc
 
+postcss:
+  cache: false
+
 paginate: 10 # Posts per page on the blog index
 paginate_path: "blog/posts/:num" # Directory base for pagination URLs eg. /posts/2/
 recent_posts: 5 # Posts in the sidebar Recent Posts section
@@ -67,6 +72,7 @@ titlecase: true # Converts page and post titles to titlecase
 collections:
   integrations:
     output: true
+    permalink: /integrations/:path/
   examples:
     output: true
   docs:
@@ -77,6 +83,12 @@ collections:
     output: true
   dashboards:
     output: true
+  guides:
+    output: true
+    permalink: /learn/:name
+  posts:
+    output: true
+    permalink: /blog/:name
 
 # ----------------------- #
 #   3rd Party Settings    #
@@ -148,9 +160,9 @@ defaults:
   # https://github.com/toshimaru/jekyll-toc/issues/116#issuecomment-644205770
   #
   - scope:
-      path: ""
       type: integrations
     values:
+      layout: integration
       toc: true
   - scope:
       path: "installation/*"
@@ -189,7 +201,10 @@ include:
 # https://github.com/toshimaru/jekyll-toc
 toc:
   min_level: 2 # default: 1
-  max_level: 3 # default: 6
+  max_level: 2 # default: 6
+
+postcss:
+  cache: false
 
 # Configuration for installation pages
 installation: