Merge pull request #2108 from supersational/hammerspoon

add Hammerspoon docs

Author: simon04

assets/javascripts/news.json

@@ -1,4 +1,8 @@
 [
+  [
+    "2024-01-12",
+    "New documentation: <a href=\"/hammerspoon/\">Hammerspoon</a>"
+  ],
   [
     "2024-01-05",
     "New documentation: <a href=\"/bazel/\">Bazel</a>"

lib/docs/filters/hammerspoon/clean_html.rb

@@ -0,0 +1,34 @@
+module Docs
+  class Hammerspoon
+    class CleanHtmlFilter < Filter
+      def call
+
+        at_css("#search").parent.remove if at_css("#search")
+
+        # Remove script tags for functionality not needed in DevDocs
+        css("script").remove
+
+        # Remove styles that are not necessary
+        css("style").remove
+
+        # Modify the main title - remove leading "docs » "
+        at_css("h1").content = at_css("h1").content.sub("docs » ", "")
+
+        # add syntax highlighting
+        css("pre").each do |pre|
+          if pre.get_attribute("lang") == "lua"
+            pre.set_attribute("data-language", "lua")
+            pre.remove_attribute("lang")
+          else
+            if pre.get_attribute("lang")
+              # logger.warn("unrecognised pre.get_attribute('lang') = #{pre.get_attribute("lang")}")
+            end
+          end
+        end
+
+        doc
+      end
+
+    end
+  end
+end

lib/docs/filters/hammerspoon/entries.rb

@@ -0,0 +1,69 @@
+module Docs
+  class Hammerspoon
+    class EntriesFilter < Docs::EntriesFilter
+      def get_name
+        at_css("h1").content
+      end
+
+      def get_type
+        slug.split("/").first
+      end
+
+      def additional_entries
+        return [] if root_page?
+        entries = []
+
+        # add a base entry
+        entries << [name, nil, name]
+
+        css("section").each do |section|
+          title_node = section.at_css("h5")
+          if title_node.nil?
+            next
+          end
+          entry_name = title_node.content.strip
+          entry_id = section["id"]
+
+          fn_type = section.at_css("a.dashAnchor").get_attribute("name")
+          # this dashAnchor is the most consistent way to get the type of the entry
+          if fn_type.start_with?("//apple_ref/cpp/Function")
+            fn_type = "Function"
+            entry_name << "()"
+          elsif fn_type.start_with?("//apple_ref/cpp/Constructor/")
+            fn_type = "Constructor"
+            entry_name << "()"
+          elsif fn_type.start_with?("//apple_ref/cpp/Method")
+            fn_type = "Method"
+            entry_name << "()"
+          elsif fn_type.start_with?("//apple_ref/cpp/Class")
+            fn_type = "Class"
+          elsif fn_type.start_with?("//apple_ref/cpp/Constant")
+            fn_type = "Constant"
+          elsif fn_type.start_with?("//apple_ref/cpp/Variable")
+            fn_type = "Variable"
+          elsif fn_type.start_with?("//apple_ref/cpp/Deprecated")
+            fn_type = "Deprecated"
+          elsif fn_type.start_with?("//apple_ref/cpp/Field")
+            fn_type = "Field"
+          else
+            fn_type = "Unknown"
+          end
+
+          # Create a new entry for each method/function
+          if fn_type != "Unknown"
+            entries << ["#{name}.#{entry_name}", entry_id, name]
+          end
+
+        end
+
+        entries
+      end
+
+      def include_default_entry?
+        # Decide when to include the default entry
+        # Here we include it unless the page is a module overview or similar
+        !subpath.end_with?("index.lp")
+      end
+    end
+  end
+end

lib/docs/scrapers/hammerspoon.rb

@@ -0,0 +1,33 @@
+module Docs
+  class Hammerspoon < UrlScraper
+    self.type = 'hammerspoon'
+    self.root_path = ''
+    self.links = {
+      home: 'https://www.hammerspoon.org',
+      code: 'https://github.com/Hammerspoon/hammerspoon'
+    }
+    self.base_url = 'https://www.hammerspoon.org/docs/'
+    self.release = '0.9.100'
+
+    html_filters.push 'hammerspoon/clean_html', 'hammerspoon/entries'
+
+    # links with no content will still render a page, this is an error in the docs
+    # (see: https://github.com/Hammerspoon/hammerspoon/pull/3579)
+    options[:skip] = ['module.lp/matrix.md']
+    options[:skip_patterns] = [
+      /LuaSkin/,
+    ]
+
+    # Hammerspoon docs don't have a license (MIT specified in the hammerspoon repo)
+    # https://github.com/Hammerspoon/hammerspoon/blob/master/LICENSE
+    options[:attribution] = <<-HTML
+      &copy; 2014–2017 Hammerspoon contributors<br>
+      Licensed under the MIT License.
+    HTML
+
+    def get_latest_version(opts)
+      get_latest_github_release('Hammerspoon', 'hammerspoon', opts)
+    end
+
+  end
+end

public/icons/docs/hammerspoon/16.png

@@ -0,0 +1 @@
+https://www.hammerspoon.org/images/hammerspoon.ico