aweplug 1.0.0.a9 → 1.0.0.a10

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c04c6ec9e220206a3579c3973bd7dd1b06696780
+  data.tar.gz: 12d68c7c2e2170dc143f8ab25c142e3cdfa64519
+SHA512:
+  metadata.gz: 8f96a65b787979b3c99e2bc47a43c9cd4628b88eb6078cbe75b6b948739782af9531f5561162292bbb7910981af19cd625eec641a72cbbac3d419b966725ae8b
+  data.tar.gz: 76e11caad4592d9d3393cc73ab21515d1ea3d83730983960ad3fcf5fcc0e84e163b706738e7b0dd993bfd77163ce9fea39bd48f7004c442e229b342bd33efa11

data/aweplug.gemspec

@@ -21,8 +21,10 @@ Gem::Specification.new do |gem|
 
   #gem.add_dependency 'awestruct', '>= 0.5.1'
   gem.add_dependency 'octokit', '>= 1.24.0'
-  gem.add_dependency 'faraday', '>= 0.8.7'
+  gem.add_dependency 'faraday', '>= 0.8.7', '< 0.9.0'
   gem.add_dependency 'faraday_middleware', '>= 0.9.0'
+  gem.add_dependency 'curb', '~> 0.8.5'
+  gem.add_dependency 'oauth', '~> 0.3.6'
 
   gem.add_development_dependency 'guard-rspec', '~> 3.0.0'
   gem.add_development_dependency 'rake', '~> 10.0.4'

data/lib/aweplug/extensions/asciidoc_example.rb

@@ -1,25 +1,73 @@
 require 'pathname'
 require 'asciidoctor'
-require 'aweplug/helpers/git_commit_metadata'
+require 'aweplug/helpers/git_metadata'
 require 'aweplug/helpers/searchisko'
 require 'json'
 require 'pry'
 
 module Aweplug::Extensions
+  # Public: An awestruct extension for guides / examples written in AsciiDoc.
+  #         Files with the .asciidoc or .adoc extension are considered to be
+  #         AsciiDoc files. This extension makes use of asciidoctor to 
+  #         render the files.
+  #
+  # Example
+  #
+  #   extension Aweplug::Extensions::AsciidocExample({...})
   class AsciidocExample 
     include Aweplug::Helper::Git::Commit::Metadata
+    include Aweplug::Helper::Git::Repository
 
-    def initialize(repository, directory, layout, output_dir, additional_excludes = [], 
-                   recurse_subdirectories = true, additional_metadata_keys = [])
-      @repo = repository
-      @output_dir = Pathname.new output_dir
-      @layout = layout
-      @recurse_subdirectories = recurse_subdirectories
-      @additional_metadata_keys = additional_metadata_keys
-      @additional_excludes = additional_excludes
-      @directory = File.join repository, directory
+    # Public: Initialization method, used in the awestruct pipeline.
+    #
+    # opts - A Hash of options, some being required, some not (default: {}). 
+    #        :repository               - The String name of the directory 
+    #                                    containing the repository (required).
+    #        :directory                - The String directory name, within the
+    #                                    :respository, containing the files 
+    #                                    (required).
+    #        :layout                   - The String name of the layout to use, 
+    #                                    omitting the extension (required).
+    #        :output_dir               - The String or Pathname of the output 
+    #                                    directory for the files (required).
+    #        :additional_excludes      - An Array of Strings containing 
+    #                                    additional base file names to exclude 
+    #                                    (default: []).
+    #        :recurse_subdirectories   - Boolean flag indicating to continue 
+    #                                    searching subdirectories (default: 
+    #                                    true).
+    #        :additional_metadata_keys - An Array of String keys from the 
+    #                                    AsciiDoc metadata to include in the 
+    #                                    searchisko payload (default: []).
+    #        :site_variable            - String name of the key within the site
+    #                                    containing additional metadata about 
+    #                                    the guide (default: value of 
+    #                                    :output_dir).
+    # Returns the created extension.
+    def initialize(opts = {})
+      required_keys = [:repository, :directory, :layout, :output_dir, :site_variable]
+      opts = {additional_excludes: [], recurse_subdirectories: true, 
+              additional_metadata_keys: [], site_variable: opts[:output_dir]}.merge opts
+      missing_required_keys = required_keys - opts.keys
+
+      raise ArgumentError.new "Missing required arguments #{missing_required_keys.join ', '}" unless missing_required_keys.empty?
+
+      @repo = opts[:repository]
+      @output_dir = Pathname.new opts[:output_dir]
+      @layout = opts[:layout]
+      @recurse_subdirectories = opts[:recurse_subdirectories]
+      @additional_metadata_keys = opts[:additional_metadata_keys]
+      @additional_excludes = opts[:additional_excludes]
+      @directory = File.join opts[:repository], opts[:directory]
+      @site_variable = opts[:site_variable]
     end
 
+    # Internal: Execute method required by awestruct. Called during the
+    # pipeline execution. No return.
+    #
+    # site - The site instance from awestruct.
+    #
+    # Returns nothing.
     def execute site
       searchisko = Aweplug::Helpers::Searchisko.new({:base_url => site.dcp_base_url, 
                                                      :authenticate => true, 
@@ -41,6 +89,7 @@ module Aweplug::Extensions
         metadata = {:author => doc.author, :commits => commit_info(@repo, path), 
                     :title => doc.doctitle, :tags => doc.attributes['tags'],
                     :toc => doc.sections.inject([]) {|result, elm| result << {:id => elm.id, :text => elm.title}; result},
+                    :github_repo_url => repository_url(@repo),
                     # Will need to strip html tags for summary
                     :summary => doc.sections.first.render}
 

data/lib/aweplug/extensions/kramdown_quickstart.rb

@@ -1,6 +1,6 @@
 require 'pathname'
 require 'kramdown'
-require 'aweplug/helpers/git_commit_metadata'
+require 'aweplug/helpers/git_metadata'
 require 'aweplug/helpers/kramdown_metadata'
 require 'aweplug/helpers/searchisko'
 require 'json'
@@ -8,15 +8,49 @@ require 'json'
 module Aweplug
   module Extensions
     module Kramdown
+      # Public: An awestruct extension for guides / examples written in AsciiDoc.
+      #         Files with the .asciidoc or .adoc extension are considered to be
+      #         AsciiDoc files. This extension makes use of asciidoctor to 
+      #         render the files.
+      #
+      # Example
+      #
+      #   extension Aweplug::Extensions::AsciidocExample({...})
       class Quickstart
         include Aweplug::Helper::Git::Commit::Metadata
+        include Aweplug::Helper::Git::Repository
 
-        def initialize repository, layout, output_dir
-          @repo = repository
-          @output_dir = Pathname.new output_dir
-          @layout = layout
+        # Public: Initialization method, used in the awestruct pipeline.
+        #
+        # opts - A Hash of options, some being required, some not (default: {}). 
+        #        :repository    - The String name of the directory containing 
+        #                         the repository (required).
+        #        :layout        - The String name of the layout to use, 
+        #                         omitting the extension (required).
+        #        :output_dir    - The String or Pathname of the output 
+        #                         directory for the files (required).
+        #        :site_variable - String name of the key within the site
+        #                         containing additional metadata about 
+        #                         the guide (default: value of 
+        #                         :output_dir).
+        # Returns the created extension.
+        def initialize opts = {}
+          required_keys = [:repository, :layout, :output_dir, :site_variable]
+          missing_required_keys = required_keys - opts.keys
+
+          raise ArgumentError.new "Missing required arguments #{missing_required_keys.join ', '}" unless missing_required_keys.empty?
+          @repo = opts[:repository]
+          @output_dir = Pathname.new opts[:output_dir]
+          @layout = opts[:layout]
+          @site_variable = opts[:site_variable] || opts[:output_dir]
         end
 
+        # Internal: Execute method required by awestruct. Called during the
+        # pipeline execution. No return.
+        #
+        # site - The Site instance from awestruct.
+        #
+        # Returns nothing.
         def execute site
           # Not sure if it's better to do this once per class, 
           # once per site, or once per invocation
@@ -30,6 +64,7 @@ module Aweplug
 
             metadata = extract_metadata(file)
             metadata[:commits] = commit_info @repo, Pathname.new(file)
+            metadata[:github_repo_url] = repository_url @repo
             converted_html = metadata.delete :converted
 
             page.send 'metadata=', metadata
@@ -62,6 +97,15 @@ module Aweplug
           end
         end
 
+
+        private
+
+        # Private: Makes use of the sepcial Kramdown parser in aweplug to pull 
+        # out metadata from the README files.
+        # 
+        # file - The String file path (relative or absolute) to parse.
+        #
+        # Returns a Hash of the metadata retrieved.
         def extract_metadata(file)
           document = parse_kramdown(file)
           toc = ::Kramdown::Converter::Toc.convert(document.root)
@@ -75,6 +119,12 @@ module Aweplug
           metadata
         end
 
+        # Private: Adds the Page to the site.
+        #
+        # site - The Site from awestruct.
+        # file - The String file path (relative or absolute) to parse.
+        # 
+        # Returns the newly constructed Page
         def add_to_site(site, file)
           page_path = Pathname.new file
           page = site.engine.load_site_page file
@@ -84,8 +134,11 @@ module Aweplug
           page
         end
 
-        private
-
+        # Private: Parses the file through Kramdown.
+        #
+        # file - The String file path (relative or absolute) to parse.
+        #
+        # Returns the parsed Kramdown Document.
         def parse_kramdown(file)
           ::Kramdown::Document.new File.readlines(file).join, :input => 'QuickStartParser' 
         end

data/lib/aweplug/handlers/synthetic_handler.rb

@@ -2,10 +2,24 @@ require 'awestruct/handlers/base_handler'
 require 'pathname'
 
 module Aweplug
+  # Public: Additional handlers for awestruct. Any handler here must extend 
+  # Awestruct::Handlers::BaseHandler.
   module Handlers
+    # Public: An awestruct handler used to create a page which has no file
+    # backing it. 
+    #
+    # Examples
+    #
+    #   Aweplug::Handlers::SyntheticHandler(site, content, output_path)
+    #   # => <Aweplug::Handlers::Synthetic:0x...>"
     class SyntheticHandler < Awestruct::Handlers::BaseHandler
       attr_reader :path
 
+      # Public: Initializer for the handler.
+      #
+      # site    - awestruct Site object.
+      # content - Content for the page, must respond to t_s.
+      # path    - output Path or String location for the generated page.
       def initialize site, content, path
         super(site)
         @content = content
@@ -19,18 +33,35 @@ module Aweplug
         end
       end
 
+      # Public: Returns the mtime for this instance
+      #
+      # page - Ignored, kept for compat with other handlers.
+      #
+      # Returns the Integer timestamp of when this object was created.
       def input_mtime(page)
         @input_mtime
       end
 
+      # Public: Returns the rendered verison of @content.
+      #
+      # context      - Ignored, kept for compatibility.
+      # with_layouts - Ignored, kept for compatibility.
+      #
+      # Returns @content.to_s.
       def rendered_content(context, with_layouts)
-        @content
+        @content.to_s
       end 
 
+      # Public: Returns @content.to_s.
+      #
+      # Returns @content.to_s.
       def raw_content
-        @content
+        @content.to_s
       end
 
+      # Public: Calculates and returns the path of @path relative to site.dir.
+      #
+      # Returns String path of @path calculated relative to site.dir. 
       def relative_source_path 
         # Copied from file_handler.rb in awestruct
         begin

data/lib/aweplug/helpers/{git_commit_metadata.rb → git_metadata.rb}

@@ -4,11 +4,23 @@ require 'json'
 module Aweplug
   module Helper
     module Git
+      module Repository
+        # Public: Returns the URL for the git repository.
+        #
+        # repo_root - The directory (relative to the site base) containing the 
+        #             git repository.
+        # remote_name - Name of the remote to retrieve, defaults to 'origin'
+        #
+        # Returns a string containing the URL of the git remote repository
+        def repository_url(repo_root, remote_name='origin') 
+          Open3.capture2(%Q[git --git-dir=#{repo_root}/.git config --get remote.#{remote_name}.url]).first.chomp[0..-5]
+        end
+      end
       module Commit
         module Metadata
           # Public: Retrieves commit information from the git repo containing the file.
           #
-          # repo_root - The directory (relative to the site base) containing  the git repo
+          # repo_root - The directory (relative to the site base) containing the git repo
           # file_path - Path to the file being processed, relative to the site base
           #
           # Returns an array of commit info as json values
@@ -21,3 +33,4 @@ module Aweplug
     end
   end
 end
+

data/lib/aweplug/helpers/kramdown_metadata.rb

@@ -3,7 +3,16 @@ require 'kramdown/parser/kramdown'
 
 module Kramdown
   module Parser
+    # Public: A Kramdown parser specific for the JBoss Quickstart format. See
+    # http://kramdown.gettalong.org/parser/kramdown.html for more information.
     class QuickStartParser < Kramdown::Parser::Kramdown
+
+      # Private: Initializer for the Parser.
+      #
+      # source  - String source of the document.
+      # options - Hash of options, see 
+      #           http://kramdown.gettalong.org/parser/kramdown.html for list
+      #           of supported options.
       def initialize source, options
         super
         @block_parsers.unshift :author_metadata
@@ -23,6 +32,7 @@ module Kramdown
       HEADER_ID=/(?:[ \t]+\{#([A-Za-z][\w:-]*)\})?/
       SETEXT_HEADER_START = /^(#{OPT_SPACE}[^ \t].*?)#{HEADER_ID}[ \t]*?\n(=)+\s*?\n/
 
+      # Internal: Parses the title to add to the metadata Hash.
       def parse_title_hack_metadata 
         return false if !after_block_boundary?
 
@@ -40,42 +50,49 @@ module Kramdown
       end
       define_parser(:title_hack_metadata, SETEXT_HEADER_START)
 
+      # Internal: Parses the author to add to the metadata Hash.
       def parse_author_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:author] = @src[2].rstrip
       end
       define_parser(:author_metadata, /^(Author:)#{OPT_SPACE}(.*?)\s*?\n/)
 
+      # Internal: Parses the level to add to the metadata Hash.
       def parse_level_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:level] = @src[2].rstrip
       end
       define_parser(:level_metadata, /^(Level:)#{OPT_SPACE}(.*?)\s*?\n/)
 
+      # Internal: Parses the technologies to add to the metadata Hash.
       def parse_technologies_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:technologies] = @src[2].rstrip
       end
       define_parser(:technologies_metadata, /^(Technologies:)#{OPT_SPACE}(.*?)\s*?\n/)
 
+      # Internal: Parses the target_product to add to the metadata Hash.
       def parse_target_product_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:target_product] = @src[2].rstrip
       end
       define_parser(:target_product_metadata, /^(Target Product:)#{OPT_SPACE}(.*?)\s*?\n/)
 
+      # Internal: Parses the source URL to add to the metadata Hash.
       def parse_source_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:source] = @src[2][1..-2].rstrip
       end
       define_parser(:source_metadata, /^(Source:)#{OPT_SPACE}(.*?)\s*?\n/)
 
+      # Internal: Parses the summary to add to the metadata Hash.
       def parse_summary_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:summary] = @src[2].rstrip
       end
       define_parser(:summary_metadata, /^(Summary:)#{OPT_SPACE}(.*?)\s*?\n/)
 
+      # Internal: Parses the product to add to the metadata Hash.
       def parse_product_metadata
         @src.pos += @src.matched_size
         @root.options[:metadata][:product] = @src[2].rstrip

data/lib/aweplug/helpers/searchisko.rb

@@ -14,6 +14,8 @@ module Aweplug::Helpers
     #        :logging - Boolean to log responses
     #        :raise_error - Boolean flag if 404 and 500 should raise exceptions
     #        :adapter - faraday adapter to use, defaults to :net_http
+    #
+    # Returns a new instance of Searchisko.
     def initialize opts={} 
       @faraday = Faraday.new(:url => opts[:base_url]) do |builder|
         if opts[:authenticate]
@@ -30,18 +32,65 @@ module Aweplug::Helpers
       end
     end
 
+    # Public: Performs a GET search against the Searchisko instance using 
+    # provided parameters.
+    #
+    # params - Hash of parameters to use as query string. See
+    #          http://docs.jbossorg.apiary.io/#searchapi for more information
+    #          about parameters and how they affect the search.
+    #
+    # Example
+    #
+    #   searchisko.search {:query => 'Search query'}
+    #   # => {...}
+    #
+    # Returns the String result of the search.
     def search params = {}
       get '/search', params
     end
 
+    # Public: Makes an HTTP GET to host/v1/rest/#{path} and returns the 
+    # result from the Faraday request.
+    #
+    # path   - String containing the rest of the path.
+    # params - Hash containing query string parameters.
+    #
+    # Example
+    #   
+    #   searchisko.get 'feed', {:query => 'Search Query'}
+    #   # => Faraday Response Object
+    #
+    # Returns the Faraday Response for the request.
     def get path, params = {}
       @faraday.get "/v1/rest/" + path, params
     end
 
+    # Public: Posts content to Searchisko.
+    #
+    # content_type - String of the Searchisko sys_content_type for the content 
+    #                being posted.
+    # content_id   - String of the Searchisko sys_content_id for the content.
+    # params       - Hash containing the content to push.
+    #
+    # Examples
+    #
+    #   searchisko.push_content 'jbossdeveloper_bom', id, content_hash
+    #   # => Faraday Response
+    #
+    # Returns a Faraday Response from the POST.
     def push_content content_type, content_id, params = {}
       post "/content/#{content_type}/#{content_id}", params
     end
 
+    # Public: Perform an HTTP POST to Searchisko.
+    #
+    # path   - String containing the rest of the path.
+    # params - Hash containing the POST body.
+    #
+    # Examples
+    #
+    #   searchisko.post "rating/#{searchisko_document_id}", {rating: 3}
+    #   # => Faraday Response
     def post path, params = {}
       @faraday.post do |req|
         req.url "/v1/rest/" + path

data/lib/aweplug/helpers/vimeo.rb

@@ -0,0 +1,127 @@
+require 'oauth'
+
+module Aweplug
+  module Helpers
+    module Vimeo
+
+      # Public: Embeds videos from vimeo inside a div. Retrieves the title
+      # and video cast from vimeo using the authenticated API.
+      # TODO Builds follow links (blog, facebook, twitter, linkedin) for any
+      # video cast, using the DCP .
+      #
+      # url - the URL of the vimeo page for the video to display
+      #
+      # Returns the html snippet
+      # 
+      def vimeo(url)
+        id = video_id(url)
+        title = video_title(id)
+        out = %Q[<div class="embedded-media">] +
+        %Q[<h4>#{title}</h4>] +
+        %Q[<iframe src="//player.vimeo.com/video/#{id}\?title=0&byline=0&portrait=0&badge=0&color=2664A2" width="500" height="313" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen}></iframe>]
+        cast = video_cast(id)
+        cast.each do |c|
+          out += %Q[<div class="follow-links">] +
+          %Q[<span class="title">Follow #{first_name(c.realname)}</span>] +
+          %Q[<a><i class="icon-rss"></i></a>] +
+          %Q[<a><i class="icon-facebook"></i></a>] +
+          %Q[<a><i class="icon-twitter"></i></a>] +
+          %Q[<a><i class="icon-linkedin"></i></a>] +
+          %Q[</div>]
+        end
+        out + %Q[</div>]
+      end
+
+      # Internal: Extracts a firstname from a full name
+      #
+      # full_name - the full name, e.g. Pete Muir
+      def first_name(full_name)
+        full_name.split[0]
+      end
+
+      # Internal: Extracts a Vimeo video id from a Vimeo video URL
+      #
+      # url - the url of the video
+      def video_id(url)
+        url.match(/^.*\/(\d*)$/)[1]
+      end
+
+      # Internal: Retrieves a video title using the Vimeo API
+      #
+      # video_id - the id of the video to fetch the title for
+      def video_title(video_id)
+        body = exec_method "vimeo.videos.getInfo", video_id
+        if body 
+          JSON.parse(body)["video"][0]["title"]
+        else
+          "Unable to fetch video info from vimeo"
+        end
+      end
+
+      # Internal: Retrieves the cast of a video using the Vimeo API
+      #
+      # video_id - the id of the video to fetch the title for
+      def video_cast(video_id)
+        body = exec_method "vimeo.videos.getCast", video_id
+        cast = []
+        if body
+          JSON.parse(body)["cast"]["member"].each do |c|
+            cast << OpenStruct.new(c)
+          end
+        end
+        cast
+      end
+
+      # Internal: Execute a method against the Vimeo API
+      #
+      # method - the API method to execute
+      # video_id - the id of the video to execute the method for
+      #
+      # Returns JSON retreived from the Vimeo API
+      def exec_method(method, video_id)
+        if access_token
+          query = "http://vimeo.com/api/rest/v2?method=#{method}&video_id=#{video_id}&format=json"
+          access_token.get(query).body
+        end
+      end
+
+      # Internal: Obtains an OAuth::AcccessToken for the Vimeo API, using the 
+      # vimeo_client_id and vimeo_access_token defined in site/config.yml and
+      # vimeo_client_secret and vimeo_access_token_secret defined in environment
+      # variables
+      # 
+      # Returns an OAuth::AccessToken for the Vimeo API 
+      def access_token
+        if @access_token
+          @access_token
+        else
+          if not ENV['vimeo_client_secret']
+            puts 'Cannot fetch video info from vimeo, vimeo_client_secret is missing from environment variables'
+            return
+          end
+          if not site.vimeo_client_id
+            puts 'Cannot fetch video info vimeo, vimeo_client_id is missing from _config/site.yml'
+            return
+          end
+          if not ENV['vimeo_access_token_secret']
+            puts 'Cannot fetch video info from vimeo, vimeo_access_token_secret is missing from environment variables'
+            return
+          end
+          if not site.vimeo_access_token
+            puts 'Cannot fetch video info from vimeo, vimeo_access_token is missing from _config/site.yml'
+            return
+          end
+          consumer = OAuth::Consumer.new(site.vimeo_client_id, ENV['vimeo_client_secret'],
+            { :site => "https://vimeo.com",
+              :scheme => :header
+            })
+          # now create the access token object from passed values
+          token_hash = { :oauth_token => site.vimeo_access_token,
+                         :oauth_token_secret => ENV['vimeo_access_token_secret']
+                       }
+          OAuth::AccessToken.from_hash(consumer, token_hash )
+        end
+      end
+    end
+  end
+end

data/lib/aweplug/version.rb

@@ -1,4 +1,4 @@
 module Aweplug
-  VERSION='1.0.0.a9'
+  VERSION='1.0.0.a10'
 end
 

data/lib/aweplug.rb

@@ -1,5 +1,6 @@
 require "aweplug/version"
 
+# Public: Main namespace for the Aweplug extensions for awestruct
 module Aweplug
   # Your code goes here...
 end