Add Jekyll plugin for Configuration Variables (home-assistant#3415)

* Add Jekyll plugin for configuration variables

* Fix requested changes

* Remove blank lines after configuration tag

* Add component/platform to configuration tag

Author: dale3h

plugins/configuration.rb

@@ -0,0 +1,114 @@
+module Jekyll
+  class ConfigurationBlock < Liquid::Block
+    TYPE_LINKS = {
+      'action'       => '/docs/scripts/',
+      'device_class' => '/components/%{component}/#device_class',
+      'template'     => '/docs/configuration/templating/',
+    }
+
+    def initialize(tag_name, text, tokens)
+      super
+      @component, @platform = text.strip.split('.', 2)
+    end
+
+    def slug(key)
+      key.downcase.strip.gsub(' ', '-').gsub(/[^\w\-]/, '')
+    end
+
+    def type_class(type)
+      ((type.is_a? Array) ? type.join(' ') : type).downcase
+    end
+
+    def type_link(type, component: nil)
+      if type.include? ','
+        type = type.split(',')
+      end
+
+      if type.is_a? Array
+        return (type.map { |t| type_link(t, component: component) }).join(' | ')
+      end
+
+      type.strip!
+      if TYPE_LINKS.include? type.downcase
+        url = TYPE_LINKS[type.downcase] % {component: component}
+        "[%s](%s)" % [type, url]
+      else
+        type
+      end
+    end
+
+    def required_value(value)
+      if value === true
+        "Required"
+      elsif value === false
+        "Optional"
+      else
+        value.strip.titlecase
+      end
+    end
+
+    def render_config_vars(vars:, component:, platform:, classes: nil)
+      result = Array.new
+      result << "<dl class='#{classes}'>"
+
+      result << vars.map do |key, attr|
+        markup = Array.new
+        markup << "<dt><a class='title-link' name='#{slug(key)}' href='\##{slug(key)}'></a> #{key}</dt>"
+        markup << "<dd>"
+        markup << "<p class='desc'>"
+        if attr.key? 'type'
+          markup << "<span class='type'>(<span class='#{type_class(attr['type'])}'>"
+          markup << "#{type_link(attr['type'], component: component)}</span>)</span>"
+        end
+        if attr.key? 'required'
+          markup << "<span class='required'>(#{required_value(attr['required'])})</span>"
+        end
+        if attr.key? 'description'
+          markup << "<span class='description'>#{attr['description']}</span>"
+        end
+        markup << "</p>"
+        if attr.key? 'default'
+          markup << "<p class='default'>Default value: #{attr['default']}</p>"
+        end
+        markup << "</dd>"
+
+        # Check for nested configuration variables
+        if attr.key? 'keys'
+          markup << "<dd>"
+          markup << render_config_vars(
+            vars: attr['keys'], component: component,
+            platform: platform, classes: 'nested')
+          markup << "</dd>"
+        end
+
+        markup
+      end
+
+      result << "</dl>"
+      result.join
+    end
+
+    def render(context)
+      if @component.nil? and @platform.nil?
+        page = context.environments.first['page']
+        @component, @platform = page['slug'].split('.', 2)
+      end
+
+      contents = super(context)
+
+      component = Liquid::Template.parse(@component).render context
+      platform  = Liquid::Template.parse(@platform).render context
+
+      vars = SafeYAML.load(contents)
+
+      <<~MARKUP
+        <div class="config-vars">
+          <h3><a class="title-link" name="configuration-variables" href="#configuration-variables"></a> Configuration Variables</h3>
+          #{render_config_vars(vars: vars, component: component, platform: platform)}
+        </div>
+      MARKUP
+    end
+  end
+end
+
+Liquid::Template.register_tag('configuration', Jekyll::ConfigurationBlock)

sass/custom/_paulus.scss

@@ -100,7 +100,6 @@ $primary-color: #049cdb;
 }
 
 .frontpage {
-
   .material-card {
     margin-bottom: 24px;
   }
@@ -109,7 +108,6 @@ $primary-color: #049cdb;
     .release-date {
       white-space: nowrap;
     }
-
   }
 
   .recent-posts {
@@ -202,7 +200,8 @@ h2:hover a.title-link,
 h3:hover a.title-link,
 h4:hover a.title-link,
 h5:hover a.title-link,
-h6:hover a.title-link {
+h6:hover a.title-link,
+dt:hover a.title-link {
   position: relative;
 
   &::before {
@@ -237,7 +236,7 @@ h6:hover a.title-link {
   }
 
   .icon i {
-  border: none !important;
+    border: none !important;
   }
 }
 
@@ -310,18 +309,31 @@ article.post, article.page, article.listing {
   h2 {
     font-size: 1.5em;
     margin-top: 2em;
+
+    // Future re-design
+    // margin: 1.5em 0 1rem;
+    //
+    // border: 0;
+    // border-top: 1px solid $primary-color;
+    // padding-top: 1.4rem;
   }
 
   h3 {
     text-transform: uppercase;
     letter-spacing: 0.125rem;
     font-size: 1.2rem;
     margin-top: 2em;
+
+    // Future re-design
+    // margin: 2em 0 1rem;
   }
 
   h4 {
     font-size: 1.1rem;
     margin-top: 2em;
+
+    // Future re-design
+    // margin: 1.5em 0 1rem;
   }
 }
 
@@ -431,7 +443,7 @@ ul.sidebar-menu {
 }
 
 a code {
-  color: #049cdb;
+  color: $primary-color;
 }
 
 twitterwidget {
@@ -447,3 +459,48 @@ twitterwidget {
   max-width: 100%;
   overflow: hidden;
 }
+
+// Configuration variables
+div.config-vars {
+  // Future re-design
+  // h3 {
+  //   border: 0;
+  //   border-top: 1px solid $primary-color;
+  //   padding-top: 1.4rem;
+  // }
+
+  dl {
+    margin-bottom: 1.5em;
+
+    &.nested {
+      border-left: 1px dotted $primary-color;
+      padding-left: 6px;
+    }
+
+    dt {
+      font-weight: bold;
+    }
+
+    dd {
+      margin: 0 0 0.5em 1em;
+
+      p.desc {
+        margin: 0;
+
+        span.type,
+        span.required {
+          font-style: italic;
+
+          &::after {
+            content: " "
+          }
+        }
+      }
+
+      p.default {
+        font-style: italic;
+        margin: 0;
+      }
+    }
+  }
+}