Documentation improvements (#10)

* Update directory names

* Rename tests

* Exclude specs from coverage

* remove DS_Store files

* Improve documentation, add debug script

* Filter assets from codecov

* update readme

* Update tests

* Fix scale

README.md

@@ -1,9 +1,9 @@
 # jekyll-apple-maps
 [![CircleCI](https://dl.circleci.com/status-badge/img/circleci/aW12qZgMpxbXNYTbdzFe5/FS3eDPqnpMpZJ2cKYi2aN9/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/circleci/aW12qZgMpxbXNYTbdzFe5/FS3eDPqnpMpZJ2cKYi2aN9/tree/main) [![codecov](https://codecov.io/gh/ZekeSnider/jekyll-apple-maps/graph/badge.svg?token=2V7NFD77OL)](https://codecov.io/gh/ZekeSnider/jekyll-apple-maps)
 
-Apple Maps plugin for Jekyll
+![Hero image for jekyll-apple-maps](/assets/hero_image.png)
 
-This gem provides [Jekyll](https://jekyllrb.com) integrations for [Apple Maps server APIs](https://developer.apple.com/documentation/applemapsserverapi/). Currently it supports the following APIs:
+This gem provides [Jekyll](https://jekyllrb.com) integrations for the [Apple Maps server APIs](https://developer.apple.com/documentation/applemapsserverapi/). It allows you to include Apple Maps content in your site using Jekyll Liquid tags. Currently it supports the following APIs:
 
 + [Snapshots](https://developer.apple.com/documentation/snapshots)
   + Supports both light and dark modes with dynamic `picture` tags
@@ -59,30 +59,97 @@ The following parameters are accepted by the block:
 + `zoom` - Zoom level with the range of `3` to `20`. Defaults to `12`.
 + `width` - Pixel width of the image. Defaults to `600`.
 + `height` -  Pixel height of the image. Defaults to `300`.
++ `scale` - The pixel density of the image. Valid values are `1`, `2`, `3`. Defaults to `2`.
 + `color_schemes` - Array of which color schemes to generate for the map. Options are `light` and `dark`. Defaults to both (`['light', 'dark']`).
 + `overlays` - An array of [overlay objects](https://developer.apple.com/documentation/snapshots/overlay). Defaults to empty `[]`.
 + `annotations` - An array of [annotation objects](https://developer.apple.com/documentation/snapshots/annotation). Defaults to empty `[]`.
 + `overlays_styles` - An array of [overlay style objects](https://developer.apple.com/documentation/snapshots/overlaystyle). Defaults to empty `[]`.
 + `images` - An array of [image objects](https://developer.apple.com/documentation/snapshots/image) for annotations. Defaults to empty `[]`.
 
 #### Examples
+A map with a single annotation
 ```
 {% apple_maps_snapshot_block %}
-  center: "33.24767,115.73192"
-  show_poi: 1
-  zoom: 14
+  center: "33.24767,-115.73192"
+  show_poi: true
+  zoom: 6
   width: 600
-  height: 150
+  height: 400
   annotations: [
     {
-      "point": "33.24767,115.73192",
-      "color": "449944",
-      "glyphText": "Salton Sea",
+      "point": "33.24767,-115.73192",
+      "color":"449944",
+      "glyphText": "S",
       "markerStyle": "large"
     }
   ]
 {% endapple_maps_snapshot_block %}
 ```
+![Example map using a single annotation](/assets/single_annotation.png)
+
+Using an image annotation
+```
+{% apple_maps_snapshot_block %}
+  center: "33.24767,-115.73192"
+  show_poi: false
+  zoom: 8
+  width: 600
+  height: 400
+  color_schemes: ["dark"]
+  annotations: [
+    {
+      "markerStyle": "img", 
+      "imgIdx": 0, 
+      "point":"33.24767,-115.73192", 
+      "color":"449944", 
+      "offset": "0,15"
+    }
+  ]
+  images: [
+    {
+      "url": "https://www.iconfinder.com/icons/2376758/download/png/48",
+      "height": 48,
+      "width": 48
+    }
+  ]
+{% endapple_maps_snapshot_block %}
+```
+![Example map using an image annotation](/assets/image_annotation.png)
+
+A map with multiple annotations
+```
+{% apple_maps_snapshot_block %}
+  center: "37.772318, -122.447326"
+  zoom: 11.5
+  width: 600
+  height: 400
+  annotations: [
+    {
+      "point": "37.819724, -122.478557",
+      "color":"red",
+      "glyphText": "G",
+      "markerStyle": "large"
+    },
+    {
+      "point": "37.750472,-122.484132",
+      "color": "blue",
+      "glyphText": "S",
+      "markerStyle": "large"
+    },
+    {
+      "point": "37.755217, -122.452776",
+      "color": "red",
+      "markerStyle": "balloon"
+    },
+    {
+      "point": "37.778457, -122.389238",
+      "color": "orange",
+      "markerStyle": "dot"
+    }
+  ]
+{% endapple_maps_snapshot_block %}
+```
+![Example map using multiple annotations](/assets/multiple_annotations.png)
 
 ## Rate limiting
 Apple specifies the following limits on usage of the Apple Maps Server APIs. This plugin caches snapshot images for the same parameters to avoid regenerating images. But if you initially generate a large number of snapshots (>25,000), you may exceed this limit.
@@ -107,6 +174,17 @@ gem build jekyll-apple-maps.gemspec
 gem install ./jekyll-apple-maps-1.0.0.gem
 ```
 
+You can also use the local version of this gem from your gemfile:
 ```
 gem 'jekyll-apple-maps', path: '/PathHere/jekyll-apple-maps'
+```
+
+There's also a CLI utility for testing templates. 
++ `-s` Is the source directory where the maps assets should be written to
++ `-r` Is the referer header to use for the request
++ `-h` prints help options
+
+When you execute the script you'll paste in the full template text (as seen above in examples).
+```
+./script/render.rb -s /YourUser/Developer/jekyll-test -r https://example.com
 ```

jekyll-apple-maps.gemspec

@@ -5,7 +5,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["[email protected]"]
 
   spec.summary       = %q{Apple Maps plugin for Jekyll}
-  spec.description   = %q{Longer description of your plugin}
+  spec.description   = %q{Provides tags for the Jekyll blogging engine to generate Apple Maps content for your site.}
   spec.homepage      = "https://github.com/zekesnider/jekyll-apple-maps"
   spec.license       = "Apache-2.0"
 

script/render.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+
+require 'jekyll'
+require 'liquid'
+require 'optparse'
+require_relative '../lib/jekyll/apple_maps/snapshot_block'
+
+# Parse command line options
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
+
+  opts.on("-s", "--source DIR", "Specify the source DIR") do |dir|
+    options[:source] = dir
+  end
+
+  opts.on("-r", "--referer URL", "Specify the referer URL") do |url|
+    options[:referer] = url
+  end
+
+  opts.on("-h", "--help", "Prints this help") do
+    puts opts
+    exit
+  end
+end.parse!
+
+# Check for required options
+if options[:source].nil? || options[:referer].nil?
+  puts "Error: Both source directory (-s) and referer URL (-r) are required."
+  puts "Use -h or --help for usage information."
+  exit 1
+end
+
+# Mock site and context
+class MockSite < Jekyll::Site
+  attr_reader :source, :config
+
+  def initialize(source, referer)
+    @config = Jekyll.configuration({'source' => source})
+    @config['apple_maps'] = { 'referer' => referer } if referer
+    super(@config)
+    @static_files = []
+    @source = source
+  end
+end
+
+site = MockSite.new(options[:source], options[:referer])
+context = Liquid::Context.new({}, {}, { site: site }, { strict_variables: true, strict_filters: true })
+
+# Register the custom tag
+Liquid::Template.register_tag('apple_maps_snapshot_block', Jekyll::AppleMaps::SnapshotBlock)
+
+puts "Enter your Apple Maps Snapshot template (press Ctrl+D when finished):"
+template = STDIN.read
+
+begin
+  # Parse the entire template
+  template = Liquid::Template.parse(template)
+
+  # Render the template
+  result = template.render(context)
+
+  puts "\nRendered output:"
+  puts result
+rescue => e
+  puts "\nError occurred:"
+  puts e.message
+  puts e.backtrace.join("\n")
+end
+
+puts "\nSite source directory: #{site.source}"
+puts "Apple Maps referer: #{site.config.dig('apple_maps', 'referer') || ''}"

spec/jekyll/apple_maps/snapshot_block_spec.rb

@@ -17,7 +17,7 @@
       {
         "point": "33.24767,115.73192",
         "color":"449944",
-        "glyphText": "Salton Sea",
+        "glyphText": "S",
         "markerStyle": "large"
       }
     ]
@@ -81,7 +81,7 @@ def image_assets
     context 'with light and dark mode' do
       it 'generates a picture tag' do
         expected_params = {
-          :annotations=>"[{\"point\":\"33.24767,115.73192\",\"color\":\"449944\",\"glyphText\":\"Salton Sea\",\"markerStyle\":\"large\"}]",
+          :annotations=>"[{\"point\":\"33.24767,115.73192\",\"color\":\"449944\",\"glyphText\":\"S\",\"markerStyle\":\"large\"}]",
           :center=>"auto",
           :imgs=>"[]",
           :lang=>"en-US",
@@ -91,7 +91,7 @@ def image_assets
           :scale=>2,
           :size=>"600x150",
           :t=>"standard",
-          :z=>14
+          :z=>14,
         }
 
         expect(client).to receive(:fetch_snapshot)
@@ -102,7 +102,7 @@ def image_assets
           .once
         rendered_content = subject.render(context)
 
-        expect(rendered_content).to eq("<picture><source srcset='/assets/maps/apple_maps_snapshot_72371e4c60df063e0bfa66136639392ddaae749743afbf4440b9998405ebeb2a.png' media='(prefers-color-scheme: light)'><source srcset='/assets/maps/apple_maps_snapshot_d8c698f67c560f562a3c46f07199bea93cf10c53832f60281725e4a58118cd6c.png' media='(prefers-color-scheme: dark)'><img src='/[\"light\", \"assets/maps/apple_maps_snapshot_72371e4c60df063e0bfa66136639392ddaae749743afbf4440b9998405ebeb2a.png\"]' alt='Map of location'></picture>")
+        expect(rendered_content).to eq("<picture><source srcset='/assets/maps/apple_maps_snapshot_7781e90ed95e1f4e0cc83da226eb2c8ee88de95a958cf31ed696979a4f2e3c15.png' media='(prefers-color-scheme: light)'><source srcset='/assets/maps/apple_maps_snapshot_a5aaa99bc91e5c070fb09cf89bbacadc95e6a9651a151d0f7a2a7e0192fc968a.png' media='(prefers-color-scheme: dark)'><img src='/[\"light\", \"assets/maps/apple_maps_snapshot_7781e90ed95e1f4e0cc83da226eb2c8ee88de95a958cf31ed696979a4f2e3c15.png\"]' alt='Map of location'></picture>")
 
         # Re-render to test regeneration of the same hash
         subject.render(context)
@@ -163,8 +163,8 @@ def image_assets
       expect(image_assets.length).to eq(4)
       Jekyll::Hooks.trigger :site, :post_write, site
       expect(image_assets.length).to eq(2)
-      expect(image_assets).to contain_exactly("/tmp/test_site/assets/maps/apple_maps_snapshot_72371e4c60df063e0bfa66136639392ddaae749743afbf4440b9998405ebeb2a.png",
-        "/tmp/test_site/assets/maps/apple_maps_snapshot_d8c698f67c560f562a3c46f07199bea93cf10c53832f60281725e4a58118cd6c.png")
+      expect(image_assets).to contain_exactly("/tmp/test_site/assets/maps/apple_maps_snapshot_7781e90ed95e1f4e0cc83da226eb2c8ee88de95a958cf31ed696979a4f2e3c15.png",
+        "/tmp/test_site/assets/maps/apple_maps_snapshot_a5aaa99bc91e5c070fb09cf89bbacadc95e6a9651a151d0f7a2a7e0192fc968a.png")
     end
   end
 end

spec/spec_helper.rb

@@ -9,6 +9,8 @@
 ]
 SimpleCov.start do
   add_filter '/spec/'
+  add_filter '/script/'
+  add_filter '/assets/'
 end
 
 RSpec.configure do |config|