openhab-scripting 4.47.0 → 5.0.0

data/lib/openhab/yard/html_helper.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module OpenHAB
+  module YARD
+    # @!visibility private
+    module HtmlHelper
+      def base_url
+        if serializer.is_a?(::YARD::Server::DocServerSerializer)
+          abs_url(base_path(router.docs_prefix), "")
+        else
+          u = url_for("")
+          u = "#{u}/" if !u.empty? && u[-1] != "/"
+          u
+        end
+      end
+
+      def url_for_search_index
+        if serializer.is_a?(::YARD::Server::DocServerSerializer)
+          url_for_list("index")
+        else
+          url_for("index.json")
+        end
+      end
+
+      def html_markup_markdown(text)
+        result = super(text)
+
+        html = Nokogiri::HTML5.fragment(result)
+        # re-link files in docs/*.md. They're written so they work on github without any
+        # processing
+        unless serializer.is_a?(::YARD::Server::DocServerSerializer)
+          html.css("a[href!='']").each do |link|
+            uri = URI.parse(link["href"])
+            next unless uri.relative? && File.extname(uri.path) == ".md"
+
+            basename = File.basename(uri.path, ".md")
+            uri.path = "file.#{basename}.html"
+            link["href"] = uri.to_s
+          end
+        end
+
+        # wtf commonmarker, you don't generate anchors?!
+        html.css("h1, h2, h3, h4, h5, h6").each do |header|
+          next if header["id"]
+
+          id = header.text.strip.downcase.delete(%(.?"')).tr(" ", "-")
+          header["id"] = id
+          header.prepend_child(%(<a href="##{id}" class="header-anchor">#</a>))
+        end
+
+        html.to_s
+      end
+
+      def link_url(url, title = nil, params = {})
+        params.merge!(@link_attrs) if defined?(@link_attrs) && @link_attrs
+        params[:class] = params.delete(:classes).join(" ") if params[:classes]
+        super
+      end
+
+      # have to completely replace this method. only change is the regex splitting
+      # into parts now allows `.` as part of the identifier
+      # rubocop:disable Style/NestedTernaryOperator, Style/StringConcatenation, Style/TernaryParentheses
+      def format_types(typelist, brackets = true) # rubocop:disable Style/OptionalBooleanParameter
+        return unless typelist.is_a?(Array)
+
+        list = typelist.map do |type|
+          type = type.gsub(/([<>])/) { h($1) }
+          type = type.gsub(/([\w:.]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) }
+          "<tt>" + type + "</tt>"
+        end
+        list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
+      end
+      # rubocop:enable Style/NestedTernaryOperator, Style/StringConcatenation, Style/TernaryParentheses
+    end
+  end
+end

data/lib/openhab/yard/markdown_helper.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module YARD
+    # @!visibility private
+    module MarkdownHelper
+      include ::YARD::Templates::Helpers::HtmlHelper
+      # @group Linking Objects and URLs
+
+      def diskfile
+        resolve_links(super)
+      end
+
+      # mostly copied from HTMLHelper
+      def resolve_links(text)
+        blockquotes = false
+        result = text.gsub(%r{(```)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+</|$)}m) do |str|
+          blockquote = $1
+          escape = $2
+          name = $3
+          title = $4
+          match = $&
+          if blockquote
+            blockquotes = !blockquotes
+            next str
+          end
+          next str if blockquotes
+
+          next(match[1..]) if escape
+
+          next(match) if name[0, 1] == "|"
+
+          if object.is_a?(String)
+            object
+          else
+            link = linkify(name, title)
+            if (link == name || link == title) && ("#{name} #{link}" !~ /\A<a\s.*>/)
+              match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text)
+              file = ((defined?(@file) && @file) ? @file.filename : object.file) || "(unknown)"
+              line = (if defined?(@file) && @file
+                        1
+                      else
+                        (object.docstring.line_range ? object.docstring.line_range.first : 1)
+                      end) + (match ? $`.count("\n") : 0)
+              if match
+                log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text#{match ? ":" : "."}\n" \
+                         "\t#{match[1] ? "..." : ""}#{match[2].delete("\n")}#{match[3] ? "..." : ""}"
+              end
+            end
+
+            link
+          end
+        end
+
+        # re-link files in docs/*.md. They're written so they work on github without any
+        # processing
+        result.gsub!(%r{\[([A-Za-z0-9,. ]+)\]\(([A-Za-z0-9./-]+)\)}) do |str|
+          title = $1
+          target = $2
+          next str unless File.dirname(target) == "docs" && File.extname(target) == ".md"
+
+          basename = File.basename(target, ".md")
+          "[#{title}](#{serializer.basepath}/file.#{basename}.html)"
+        end
+
+        result
+      end
+
+      # mostly copied from HTMLHelper
+      def link_object(obj, title = nil, anchor = nil, relative = true) # rubocop:disable Style/OptionalBooleanParameter
+        return title if obj.nil?
+
+        obj = ::YARD::Registry.resolve(object, obj, true, true) if obj.is_a?(String)
+
+        was_const = false
+        # Re-link references to constants that are aliases to their target. But keep
+        # their current title.
+        while obj.is_a?(::YARD::CodeObjects::ConstantObject) && obj.target
+          title ||= h(object.relative_path(obj)).to_s
+          was_const = true
+          obj = obj.target
+        end
+        return link_object(obj, title, anchor, relative) if was_const
+
+        title = if title
+                  title.to_s
+                elsif object.is_a?(::YARD::CodeObjects::Base)
+                  # Check if we're linking to a class method in the current
+                  # object. If we are, create a title in the format of
+                  # "CurrentClass.method_name"
+                  if obj.is_a?(::YARD::CodeObjects::MethodObject) && obj.scope == :class && obj.parent == object
+                    h([object.name, obj.sep, obj.name].join)
+                  elsif obj.title != obj.path
+                    h(obj.title)
+                  else
+                    h(object.relative_path(obj))
+                  end
+                else
+                  h(obj.title)
+                end
+        return title unless serializer
+        return title if obj.is_a?(::YARD::CodeObjects::Proxy)
+
+        link = url_for(obj, anchor, relative)
+        link ? link_url(link, title, title: h("#{obj.title} (#{obj.type})")) : title
+      rescue ::YARD::Parser::UndocumentableError
+        log.warn "The namespace of link #{obj.inspect} is a constant or invalid."
+        title || obj.to_s
+      end
+
+      def url_for(obj, anchor = nil, relative = true) # rubocop:disable Style/OptionalBooleanParameter
+        link = nil
+        return link unless serializer
+        return link if obj.is_a?(::YARD::CodeObjects::Base) && run_verifier([obj]).empty?
+
+        if obj.is_a?(::YARD::CodeObjects::Base) && !obj.is_a?(::YARD::CodeObjects::NamespaceObject)
+          # If the obj is not a namespace obj make it the anchor.
+          anchor = obj
+          obj = obj.namespace
+        end
+
+        objpath = serializer.serialized_path(obj)
+        return link unless objpath
+
+        relative = false if object == ::YARD::Registry.root
+        if relative
+          fromobj = object
+          if object.is_a?(::YARD::CodeObjects::Base) &&
+             !object.is_a?(::YARD::CodeObjects::NamespaceObject)
+            fromobj = owner
+          end
+
+          from = serializer.serialized_path(fromobj)
+          link = File.relative_path(from, objpath)
+        else
+          link = File.join(serializer.basepath, objpath)
+        end
+
+        link + (anchor ? "##{urlencode(anchor_for(anchor))}" : "")
+      end
+
+      def link_url(url, title = nil, _params = nil)
+        title ||= url
+        "[#{title}](#{url})"
+      end
+    end
+  end
+end

data/lib/openhab/yard/tags/constant_directive.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module YARD
+    module Tags
+      class ConstantDirective < ::YARD::Tags::Directive
+        def call
+          return unless handler
+
+          ::YARD::CodeObjects::ConstantObject.new(handler.namespace, tag.name.to_sym) do |obj|
+            obj.value = ""
+            obj.docstring = tag.text
+          end
+        end
+
+        ::YARD::Tags::Library.define_directive :constant, :with_title_and_text, self
+      end
+    end
+  end
+end

data/lib/openhab/yard/tags/group_directive.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module YARD
+    module Tags
+      module GroupDirective
+        ::YARD::Tags::GroupDirective.prepend(self)
+
+        def after_parse
+          return if tag.name.empty?
+          return unless handler
+
+          object = CodeObjects::GroupObject.new(handler.namespace, tag.name)
+          handler.extra_state.group = object
+          self.parser = parser.class.new(parser.library)
+          parser.state.inside_directive = true
+          parser.parse(tag.text, object, handler)
+          parser.state.inside_directive = false
+          object.docstring = parser.to_docstring # rubocop:disable Lint/UselessSetterCall
+        end
+      end
+    end
+  end
+end

data/lib/openhab/yard/tags/library.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+YARD::Tags::Library.define_directive :group, :with_title_and_text, YARD::Tags::GroupDirective

data/lib/openhab/yard.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "byebug"
+
+Dir[File.expand_path("yard/**/*.rb", __dir__)].sort.each do |f|
+  require f
+end
+
+YARD::Templates::Template.extra_includes << OpenHAB::YARD::BaseHelper
+YARD::Templates::Template.extra_includes << ->(opts) { OpenHAB::YARD::CodeRay::HtmlHelper if opts.format == :html }
+YARD::Templates::Template.extra_includes << ->(opts) { OpenHAB::YARD::HtmlHelper if opts.format == :html }
+YARD::Templates::Template.extra_includes << ->(opts) { OpenHAB::YARD::MarkdownHelper if opts.format == :markdown }
+
+YARD::Templates::Engine.register_template_path File.expand_path("../../templates", __dir__)
+YARD::Tags::Library.define_tag "Java Interface", :interface
+
+YARD::Server.register_static_path(".")
+
+#
+# @!parse
+#   # @!visibility private
+#   module Comparable; end
+#
+#   # @!visibility private
+#   module Forwardable; end
+#
+#   # @!visibility private
+#   module Singleton; end
+#
+#   # Extensions to Ruby Numeric
+#   class Numeric; end
+#
+#   # @!visibility private
+#   class Object; end
+#
+#   # Extensions to Ruby Range
+#   class Range; end
+#