slate_algolia 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e80c2ccf5f876da5001c305e6d272a21287e313d
-  data.tar.gz: 8e96a63ef046eef75dc8c32dbccf3e837acf892d
+  metadata.gz: d7501fd269fa65aa278b4e78674e7fcb2236ac63
+  data.tar.gz: b181aa3c1968582c0a5b817cd5ee9c99bb042b57
 SHA512:
-  metadata.gz: 87591952fd37a850f76772d4a4935210cbcef20f7a38f3015f8fd187b6ebc78ee83170cd80a9bd77d84b13ee41db0a5cf7cbbd6e7a49401652069bd01d6092f6
-  data.tar.gz: f5ef2a9aeb23290ab53e4b03cfc9cb8f1fb49b4a9bcc68ecda146c294c4863f342e1115d99043313dcdbb6b0065c78ef93559947b89327136597de2335be653e
+  metadata.gz: d05ec3b8c68eec7f1ec8bf1c1fb22665374bbcafaa364feaa93fd9a2e5da07af5dd304a936faf92317bad3c1f1e393b934c6880811138a8dde3b0ef99d48b20f
+  data.tar.gz: b79afe1e0dbf732f73fdb56c307317170b3bb3c00619ae2acaddc2bc3ab0cf714d930346d3474086199c9931be21c655a29e95bd259930ebab983dea92565e43

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## What does this PR do?
+
+## How should this be tested?
+
+Step through the code line by line. Things to keep in mind as you review:
+ - Are there any edge cases not covered by this code?
+ - Does this code follow conventions (naming, formatting, modularization, etc) where applicable?
+
+## Related tickets?

data/.gitignore

@@ -2,4 +2,5 @@
 /Gemfile.lock
 
 # Ignore pkg folder
-/pkg
+/pkg
+/tmp

data/.rubocop.yml

@@ -0,0 +1,5 @@
+Style/BracesAroundHashParameters:
+  EnforcedStyle: context_dependent
+
+LineLength:
+    Max: 120

data/CONTRIBUTING.md

@@ -29,6 +29,15 @@ If a maintainer asks you to "rebase" your PR, they're saying that a lot of code
 ```ssh
 $ git clone https://github.com/keen/slate_algolia.git && cd slate_algolia
 $ bower install
+
+# Run the specs
+bundle exec rake spec
+
+# Run the style guide
+bundle exec rake style
+
+# Run the full test suite
+bundle exec rake
 ```
 
 ### Submitting a Pull Request

data/Gemfile

@@ -12,7 +12,8 @@ group :development do
 end
 
 group :test do
-  gem 'cucumber'
-  gem 'aruba'
   gem 'rspec'
+  gem 'middleman'
+  gem 'webmock'
+  gem 'rubocop', require: false
 end

data/README.md

@@ -4,7 +4,26 @@
 
 ## Installation
 
-The most simple way to activate this is to add this code to your `config.rb`:
+If you're not using Bundler, simply install the gem:
+
+```ssh
+gem install slate_algolia
+```
+
+If you are using Bundler, add `slate_algolia` to your Gemfile
+```ruby
+gem slate_algolia
+```
+
+and then reinstall your gems
+
+```ssh
+bundle install
+```
+
+## Configuration
+
+The most simple way to activate the extension is to add this code to your `config.rb`:
 
 ```ruby
 activate :slate_algolia do |options|
@@ -19,8 +38,6 @@ You also need to add a line to the YAML Frontmatter of your Slate docs index. Th
 algolia_search: true
 ```
 
-## Configuration
-
 There are some additional configurations you can enable:
 
 ```ruby
@@ -29,9 +46,48 @@ activate :slate_algolia do |options|
   options.api_key        = '1234'  # Algolia API Key
   options.dry_run        = true    # Don't send data to Algolia, but output some log information instead
   options.parsers        = {}      # Custom tag parsers (discussed later in the docs)
+  options.before_index   = nil     # Proc for changing the data model before it is sent to Algolia
+end
+```
+
+## Changing the Data Model
+
+While the data model built in is pretty well thought-out, everyone's search needs will be different. Some projects of course will need to mold the data model to meet their needs. To do that, you can hook in to the indexing process and modify the records _just before_ they are shipped off to Algolia.
+
+Set it up in your config file:
+
+```ruby
+activate :slate_algolia do |options|
+  options.before_index = proc { |record|
+    # Change the key name for the body to 'content'
+    record[:content] = record[:body]
+    record.delete(:body)
+
+    record
+  }
 end
 ```
 
+If you would like to turn a single record into multiple records, simply return an array of records
+
+```ruby
+activate :slate_algolia do |options|
+  options.before_index = proc { |record|
+    # Create a record for each language in the code examples
+    record.permanent_code.map.with_index { |language, code|
+      new_record = record.merge({
+        code: code,
+        language: language
+      })
+      new_record.delete(permanent_code)
+
+      new_record
+    }
+  }
+end
+```
+
+
 ## Custom Tag Parser
 
-TODO
+TODO

data/Rakefile

@@ -1,14 +1,7 @@
-require 'bundler'
-Bundler::GemHelper.install_tasks
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
-require 'cucumber/rake/task'
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:style)
 
-Cucumber::Rake::Task.new(:cucumber, 'Run features that should pass') do |t|
-  t.cucumber_opts = "--color --tags ~@wip --strict"
-end
-
-require 'rake/clean'
-
-task test: ['cucumber']
-
-task default: :test
+task default: [:spec, :style]

data/lib/slate_algolia/extension.rb

@@ -3,77 +3,102 @@ require 'slate_algolia/parser'
 require 'slate_algolia/index'
 
 module Middleman
-    module SlateAlgolia
-        class Extension < Middleman::Extension
-            option :parsers, {}, 'Custom tag parsers'
-            option :dry_run, false, 'Send data to Algolia or not?'
-            option :application_id, '', 'Algolia Application ID'
-            option :api_key, '', 'Algolia API Key'
-
-            def initialize(app, options_hash={}, &block)
-                super
-
-                tag_parsers = set_parser_defaults(options.parsers)
-                dry_run = options.dry_run
-                application_id = options.application_id
-                api_key = options.api_key
-
-                app.after_build do |builder|
-                    sitemap.where(:algolia_search.equal => true).all.each do |slate_page|
-                        content_parser = Parser.new(slate_page, tag_parsers)
-
-                        if content_parser.sections.length > 0
-                            index = Index.new(application_id, api_key, dry_run)
-
-                            content_parser.sections.each do |section|
-                                index.queue_object(section)
-                            end
-
-                            index.flush_queue
-                            index.clean_index
-                        end
-                    end
-                end
+  module SlateAlgolia
+    # Base extension orchestration
+    class Extension < Middleman::Extension
+      option :parsers, {}, 'Custom tag parsers'
+      option :dry_run, false, 'Send data to Algolia or not?'
+      option :application_id, '', 'Algolia Application ID'
+      option :index_name, 'API Docs', 'Name for the Algolia Index'
+      option :api_key, '', 'Algolia API Key'
+      option :before_index, nil, 'A block to run on each record before it is sent to the index'
+
+      def initialize(app, options_hash = {}, &block)
+        super
+        merge_parser_defaults(options.parsers)
+      end
+
+      def after_build
+        parse_content
+        index.flush_queue
+        index.clean_index
+      end
+
+      def index
+        @index ||= Index.new(
+          application_id: options.application_id,
+          api_key: options.api_key,
+          name: options.index_name,
+          dry_run: options.dry_run,
+          before_index: options.before_index
+        )
+      end
+
+      # rubocop:disable AbcSize, MethodLength
+      def parsers
+        @parsers ||= {
+          pre: lambda do |node, section, page|
+            languages = node.get('class').split
+            languages.delete('highlight')
+
+            if languages.length
+
+              # if the current language is in the list of language tabs
+              code_type = if page.metadata[:page]['language_tabs'].include?(languages.first)
+                            :tabbed_code
+                          else
+                            :permanent_code
+                          end
+
+              section[code_type] = {} unless section[code_type]
+
+              section[code_type][languages.first.to_sym] = node.text
             end
 
-            private
-
-            def parser_defaults
-                {
-                    pre: -> (node, section, page) do 
-                        languages = node.get('class').split
-                        languages.delete('highlight')
-
-                        if languages.length
-
-                            # if the current language is in the list of language tabs
-                            if page.metadata[:page]['language_tabs'].include?(languages.first)
-                                code_type = :tabbed_code
-                            else
-                                code_type = :permanent_code
-                            end
-
-                            unless section[code_type]
-                                section[code_type] = {}
-                            end
-
-                            section[code_type][languages.first.to_sym] = node.text
-                        end
-                    end,
-
-                    blockquote: -> (node, section, page) do
-                        unless section[:annotations]
-                            section[:annotations] = []
-                        end
-
-                        section[:annotations].push(node.text)
-                    end
-                }
-            end
-
-            def set_parser_defaults(custom_parsers)
-                parser_defaults.merge(custom_parsers)
-            end
+            section
+          end,
+
+          blockquote: lambda do |node, section, _page|
+            section[:annotations] = [] unless section[:annotations]
+            section[:annotations].push(node.text)
+            section
+          end,
+
+          h1: lambda do |node, _section, _page|
+            {
+              objectID: node.get('id'),
+              title: node.text,
+              body: ''
+            }
+          end,
+
+          h2: lambda do |node, _section, _page|
+            {
+              objectID: node.get('id'),
+              title: node.text,
+              body: ''
+            }
+          end
+        }
+      end
+      # rubocop:enable AbcSize, MethodLength
+
+      private
+
+      def parse_content
+        app.sitemap.where(:algolia_search.equal => true).all.each do |slate_page|
+          content_parser = Parser.new(slate_page, parsers)
+          next if content_parser.sections.empty?
+
+          content_parser.sections.each do |section|
+            index.queue_object(section)
+          end
         end
+      end
+
+      def merge_parser_defaults(custom_parsers)
+        parsers.merge(custom_parsers)
+      end
     end
+  end
 end

data/lib/slate_algolia/index.rb

@@ -1,51 +1,68 @@
 require 'algoliasearch'
 
 module Middleman
-    module SlateAlgolia
-        class Index
-
-            def initialize(app_id, api_key, dry_run = false)
-                @publish = !dry_run
-                @published = []
-
-                Algolia.init :application_id => app_id,
-                             :api_key        => api_key
-
-                @index = Algolia::Index.new("API Docs")
-                @queue = []
-            end
-
-            def queue_object(data)
-                @queue.push(data)
-
-                if @queue.length >= 1000
-                    flush_queue()
-                end
-            end
-
-            def clean_index
-                old_content = @index.browse['hits'].reject { |hit|
-                    @published.any? { |entry| entry[:id] == hit['id'] }
-                }
-
-                if @publish
-                    @index.delete_objects(old_content.map { |hit| hit['objectID'] })
-                else
-                    puts "would have deleted #{old_content.size} items if not in dry mode"
-                end
-            end
-
-            def flush_queue
-                to_publish = @queue.reject { |obj| obj[:id].nil? }
-                if @publish
-                    @index.add_objects(to_publish)
-                else
-                    puts "would have published #{to_publish.size} items if not in dry mode"
-                end
-
-                @published.concat(to_publish)
-                @queue = []
-            end
+  module SlateAlgolia
+    # Manages the Index stored in Algolia
+    class Index
+      def initialize(options)
+        @options = options
+        @publish = !@options[:dry_run]
+        @published = []
+
+        Algolia.init application_id: @options[:application_id],
+                     api_key: @options[:api_key]
+
+        @index = Algolia::Index.new(options[:name])
+        @queue = []
+      end
+
+      def queue_object(data)
+        @queue.push(data)
+
+        flush_queue if @queue.length >= 1000
+      end
+
+      def clean_index
+        old_content = @index.browse['hits'].reject do |hit|
+          @published.any? { |entry| entry[:id] == hit['id'] }
+        end
+
+        if @publish
+          @index.delete_objects(old_content.map { |hit| hit['objectID'] })
+        else
+          puts "would have deleted #{old_content.size} items if not in dry mode"
+        end
+      end
+
+      def run_before_index
+        return @queue unless @options[:before_index].instance_of?(Proc)
+
+        @queue = @queue.map do |record|
+          new_record = @options[:before_index].call(record)
+          if new_record
+            new_record
+          else
+            record
+          end
+        end
+
+        @queue.flatten!
+      end
+
+      def flush_queue
+        run_before_index
+
+        to_publish = @queue.reject { |obj| obj[:objectID].nil? }
+
+        if @publish
+          @index.add_objects(to_publish)
+        else
+          puts "would have published #{to_publish.size} items if not in dry mode"
         end
+
+        @published.concat(to_publish)
+        @queue = []
+      end
     end
+  end
 end

data/lib/slate_algolia/parser.rb

@@ -1,58 +1,79 @@
 require 'oga'
 
 module Middleman
-    module SlateAlgolia
-        class Parser
-
-            def initialize(middleman_page, parsers)
-                @middleman_page = middleman_page
-                @page = Oga.parse_html(middleman_page.render({}, {current_page: middleman_page }))
-                @parsers = parsers
-                get_content
-                generate_sections
-            end
-
-            def sections
-                @sections ||= []
-            end
-
-            private
-
-            def get_content
-                @content = @page.css('.content').first
-            end
-
-            def generate_sections
-                @sections = []
-                current_section = {title: 'introduction-header'}
-
-                @content.children.each do |node|
-                    next unless node.class  == Oga::XML::Element
-
-                    if node.name == 'h1' or node.name == 'h2'
-                        @sections.push(current_section) unless current_section[:title].nil? and current_section[:body].empty?
-                        current_section = {
-                            id: node.get('id'),
-                            title: node.text
-                        }
-                    else
-                        parser = @parsers[node.name.to_sym] || self.method(:default_tag_parser)
-                        parser.call(node, current_section, @middleman_page)
-                    end
-                end
-
-                @sections.push(current_section)
-            end
-
-            def default_tag_parser(node, section, page)
-                if section[:body]
-                    section[:body] += "\n"
-                else
-                    section[:body] = ""
-                end
-
-                section[:body] += node.text
-            end
+  module SlateAlgolia
+    # Parses the HTML and translates it to an Index Record format
+    class Parser
+      def initialize(middleman_page, parsers)
+        @middleman_page = middleman_page
+        @page = Oga.parse_html(
+          middleman_page.render(
+            {},
+            { current_page: middleman_page }
+          )
+        )
+        @parsers = parsers
+        generate_sections
+      end
+
+      def sections
+        @sections ||= []
+      end
+
+      private
+
+      def content
+        @content ||= @page.css('.content').first
+      end
+
+      def generate_sections
+        current_section = {
+          objectID: 'intro',
+          title: 'introduction-header',
+          body: ''
+        }
+
+        content.children.each do |node|
+          next unless node.class == Oga::XML::Element
+          current_section = parse_node(node, current_section, @middleman_page)
+        end
+
+        sections.push(current_section)
+      end
+
+      def handle_new_section(node, current_section)
+        if node.name == 'h1' || node.name == 'h2'
+          unless current_section[:title].nil? &&
+                 current_section[:body].empty?
+
+            sections.push(current_section)
+          end
+
+          {}
+        else
+          current_section
+        end
+      end
+
+      def parse_node(node, section, page)
+        section = handle_new_section(node, section)
+        parser = @parsers[node.name.to_sym] ||
+                 method(:default_tag_parser)
+
+        parser.call(node, section, page)
+      end
+
+      def default_tag_parser(node, section, _page)
+        if section[:body]
+          section[:body] += '\n'
+        else
+          section[:body] = ''
         end
+
+        section[:body] += node.text
+
+        section
+      end
     end
+  end
 end

data/lib/slate_algolia.rb

@@ -1,6 +1,8 @@
 require 'middleman-core'
+require 'slate_algolia/index'
+require 'slate_algolia/parser'
+require 'slate_algolia/extension'
 
 ::Middleman::Extensions.register(:slate_algolia) do
-    require 'slate_algolia/extension'
-    ::Middleman::SlateAlgolia::Extension
+  ::Middleman::SlateAlgolia::Extension
 end

data/slate_algolia.gemspec

@@ -1,21 +1,20 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
 
 Gem::Specification.new do |s|
-  s.name        = "slate_algolia"
-  s.version     = "0.0.1"
+  s.name        = 'slate_algolia'
+  s.version     = '1.0.0'
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Joe Wegner"]
-  s.email       = ["joe@wegnerdesign.com"]
-  s.summary     = "Quickly and easily index Slate Docs in Algolia"
+  s.authors     = ['Joe Wegner']
+  s.email       = ['joe@wegnerdesign.com']
+  s.summary     = 'Quickly and easily index Slate Docs in Algolia'
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
-  
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.require_paths = ['lib']
+
   # The version of middleman-core your extension depends on
-  s.add_runtime_dependency("middleman-core", ["~> 3.3", ">= 3.3.12"])
-  s.add_runtime_dependency("oga", ["~> 1.3", ">= 1.3.1"])
-  s.add_runtime_dependency("algoliasearch", ["~> 1.6", ">= 1.6.1"])
+  s.add_runtime_dependency('middleman-core', ['~> 3.3', '>= 3.3.12'])
+  s.add_runtime_dependency('oga', ['~> 1.3', '>= 1.3.1'])
+  s.add_runtime_dependency('algoliasearch', ['~> 1.6', '>= 1.6.1'])
 end