usmu 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed2e494db784cf3a3c1eb959eb36cd23460e9f4e
-  data.tar.gz: 300f0c268563caa186ade7f41d84a12a2d72c4fe
+  metadata.gz: 8fc86dae15be6aceae0a11ed6b8d31b381eb2fda
+  data.tar.gz: e86a3100c2b95c4f095597c12b302eee60e61352
 SHA512:
-  metadata.gz: e338182d6654d55cd1495d12702b3dbdac35a48fa9c79ebec0c846fb75bf01cbcbdbd230a2fa279c56eb01ccca9d0dd64e3aa92a996ec2d826debeb54e9b70ad
-  data.tar.gz: b528d3ccb26688545f2c3ea277edfab575abe72d266be8fc361d8fb1a1762c360d30cc905a8842da20232a8b2ab85d530a898f67804f9b8517f3e81527a0ec97
+  metadata.gz: f198fb4e39bf471a56324c001216e2eee1041b9c04ec8f842d2c62c36dc0524f1e15598ae097aaf6af395b2ca8f249030f7748d1bd9636351f2c4d2afe86fade
+  data.tar.gz: bfee2b4b896e7d1dd990beb33eb0c76c9e80647f29e4cb6cbc9afee036a6aff166b7a1ce3f57e83d4c304a0086fec0c9cad2b294fd29fb9423ca776170be8279

data/.yardopts

@@ -1 +1 @@
---private --protected --hide-void-return -m markdown -M redcarpet lib/**/*.rb - README.md
+--private --protected --default-return void -m markdown -M redcarpet -- lib/**/*.rb - README.md CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Usmu Change Log
 
+## 0.3.1
+
+Matthew Scharley <matt.scharley@gmail.com>
+
+* Add gemnasium badge (9449a8e605a3176a5e43d289cf7c0da9f38aa5ea)
+* Add a bunch of documentation (c1eca0f79f7beecaf945237a425f8963846e83a3)
+* Fix a few issues from cane (bae78ee394af4fc86d71d8754434a8c6f04100e7)
+* Small fixups for the build scripts (d14b0b2822c704103896f7b462640709704f04b7)
+* Allow Configuration to be indexed with a full path safely (110965b9058970ba82ee36bf4bc491e110996ad4)
+
 ## 0.3.0
 
 Matthew Scharley <matt.scharley@gmail.com>

data/README.md

@@ -1,4 +1,4 @@
-# usmu [![Build Status](https://travis-ci.org/usmu/usmu.svg?branch=master)](https://travis-ci.org/usmu/usmu)
+# usmu [![Build Status](https://travis-ci.org/usmu/usmu.svg?branch=master)](https://travis-ci.org/usmu/usmu) [![Dependency Status](https://gemnasium.com/usmu/usmu.svg)](https://gemnasium.com/usmu/usmu)
 
 **Source:** [https://github.com/usmu/usmu](https://github.com/usmu/usmu)  
 **Author:** Matthew Scharley  

data/lib/usmu.rb

@@ -64,6 +64,7 @@ module Usmu
   end
   # :nocov:
 
+  # @return [Usmu::Plugin] a handler to the plugin interface
   def self.plugins
     @plugins ||= Usmu::Plugin.new
   end

data/lib/usmu/configuration.rb

@@ -76,11 +76,33 @@ module Usmu
     # working directory to the configuration file and other factors. The accessor functions such as `#source_path`
     # should be preferred for most usages.
     #
-    # @param [String, Symbol] index The index to return.
-    # @return [Array, Hash, String, Symbol] Returns a value from the hash loaded from YAML. The type of value will
-    #   ultimately depend on the configuration file and the index provided.
-    def [](index)
-      @config[index]
+    # @param [String, Symbol] indices
+    #   A list of indices to use to find the value to return. Can also include an options hash with the
+    #   following options:
+    #
+    #   * `:default`: Sets the default value if the value can't be found.
+    #
+    # @return [Array, Hash, String, Symbol]
+    #   Returns a value from the hash loaded from YAML. The type of value will ultimately depend on the configuration
+    #   file and the indices provided.
+    def [](*indices)
+      if indices[-1].class.name == 'Hash'
+        opts = indices.pop
+      else
+        opts = {}
+      end
+
+      value = @config
+      while indices.length > 0
+        i = indices.shift
+        if value.key? i
+          value = value[i]
+        else
+          return opts[:default]
+        end
+      end
+
+      value
     end
 
     private
@@ -123,7 +145,6 @@ module Usmu
     # Helper function to search a directory recursively and return a list of files that are renderable.
     #
     # @param [String] directory the directory to search
-    # @param [Boolean] layout is this directory a layouts_path
     # @return [Array<Usmu::Layout>, Array<Usmu::StaticFile>] Either an array of Layouts or StaticFiles in the directory
     def get_files(directory)
       Dir["#{directory}/**/{*,.??*}"].

data/lib/usmu/plugin.rb

@@ -1,6 +1,9 @@
 
 module Usmu
+  # Singletonish class to load plugins and act as an interface to them. Shouldn't be created directly.
+  # @see Usmu.plugins
   class Plugin
+    # Constructor for the plugin interface.
     def initialize
       @log = Logging.logger['Usmu::Plugin']
     end
@@ -9,24 +12,12 @@ module Usmu
     # with the string 'usmu-' will be recognised as a plugin. This will load the gem according to the RubyGems
     # recommendations for naming schemes. A gem named `usmu-s3_uploader` will be loaded by requiring the path
     # `'usmu/s3_uploader'` and then then the class `Usmu::S3Uploader` will be instantiated as the plugins interface.
-    #
-    # @return [void]
     def load_plugins
-      loaded = []
+      @loaded = []
       @log.debug('Loading plugins')
       @log.debug('Loaded Usmu::Plugin::Core')
       plugins.push Usmu::Plugin::Core.new
-      Gem::Specification.find_all { |s| s.name =~ /^usmu-/ }.each do |spec|
-        load_path = spec.name.gsub('-', '/')
-        require load_path
-
-        unless loaded.include? load_path
-          loaded << load_path
-          klass = load_path.split('/').map {|s| s.split('_').map(&:capitalize).join }.join('::')
-          @log.debug("Loading plugin #{klass} from '#{load_path}'")
-          plugins.push plugin_get(klass)
-        end
-      end
+      Gem::Specification.find_all { |s| s.name =~ /^usmu-/ }.each &method(:load_gem)
       @log.debug("Loaded: #{plugins.inspect}")
     end
 
@@ -38,9 +29,11 @@ module Usmu
 
     # Call all plugins and collate any data returned. nil can be returned explicitly to say this plugin has nothing to
     # return.
+    #
     # @param [Symbol] method The name of the method to call. This should be namespaced somehow. For example, a plugin
     #                        called `usmu-s3` could use the method namespace `s3` and have a hook called `:s3_upload`
     # @param [Array] args The arguments to pass through to plugins. Can be empty.
+    # @return [Array] An array of non-nil values returned from plugins
     def invoke(method, *args)
       @log.debug("Invoking plugin API #{method}")
       plugins.map do |p|
@@ -55,11 +48,31 @@ module Usmu
 
     private
 
+    # Helper function to load and instantiate plugin classes
+    #
+    # @param [String] klass The name of the class to load
+    # @return [Object] A plugin object
     def plugin_get(klass)
       object.const_get(klass).new
     rescue NameError
       # Ruby 1.9.3, dowp
       klass.split('::').reduce(Object) {|memo, o| memo.const_get o }.new
     end
+
+    # Helper function to load a plugin from a gem specification
+    #
+    # @param [Gem::Specification] spec
+    def load_gem(spec)
+      load_path = spec.name.gsub('-', '/')
+      require load_path
+
+      unless @loaded.include? load_path
+        @loaded << load_path
+        klass = load_path.split('/').map {|s| s.split('_').map(&:capitalize).join }.join('::')
+        @log.debug("Loading plugin #{klass} from '#{load_path}'")
+        plugins.push plugin_get(klass)
+      end
+      nil
+    end
   end
 end

data/lib/usmu/plugin/core.rb

@@ -2,11 +2,18 @@ require 'fileutils'
 
 module Usmu
   class Plugin
+    # Usmu Core's plugin. We dog-food several plugin integration points.
     class Core
+      # Basic constructor.
       def initialize
         @log = Logging.logger[self]
       end
 
+      # We add two commands: `generate` and `init [path]`.
+      #
+      # @see #command_generate
+      # @see #command_init
+      # @see Usmu::Plugin::CoreHooks#commands
       def commands(ui, c)
         @log.debug('Adding core console commands...')
         @ui = ui
@@ -23,12 +30,19 @@ module Usmu
         end
       end
 
-      # @return [void]
+      # Command to generate a website.
+      #
+      # @param [Array<String>] args arguments passed by the user.
+      # @param [Hash] options options parsed by Commander
       def command_generate(args, options)
         @site_generator = Usmu::SiteGenerator.new(@ui.configuration)
         @site_generator.generate
       end
 
+      # Command to initialise a new website.
+      #
+      # @param [Array<String>] args arguments passed by the user.
+      # @param [Hash] options options parsed by Commander
       def command_init(args, options)
         @log.info("Usmu v#{Usmu::VERSION}")
         @log.info('')
@@ -42,14 +56,23 @@ module Usmu
         from = File.realpath(File.join(File.dirname(__FILE__), '../../../share/init-site'))
 
         @log.info("Copying #{from} -> #{path}")
-        Dir["#{from}/**/{*,.??*}"].each do |file|
-          output_name = file[(from.length + 1)..file.length]
-          @log.success "Creating #{output_name}..."
-          unless File.directory? file
-            output_path = "#{path}/#{output_name}"
-            FileUtils.mkdir_p File.dirname(output_path) unless File.directory? File.dirname(output_path)
-            FileUtils.copy(file, output_path)
-          end
+        Dir["#{from}/**/{*,.??*}"].each {|f| init_copy_file(from, path, f) }
+      end
+
+      private
+
+      # Helper to copy a file.
+      #
+      # @param [String] from
+      # @param [String] to
+      # @param [String] file
+      def init_copy_file(from, to, file)
+        output_name = file[(from.length + 1)..file.length]
+        @log.success "Creating #{output_name}..."
+        unless File.directory? file
+          output_path = "#{to}/#{output_name}"
+          FileUtils.mkdir_p File.dirname(output_path) unless File.directory? File.dirname(output_path)
+          FileUtils.copy(file, output_path)
         end
       end
     end

data/lib/usmu/plugin/core_hooks.rb

@@ -0,0 +1,14 @@
+
+module Usmu
+  class Plugin
+    # This class describes all the hooks available from Usmu Core.
+    # @api hooks
+    class CoreHooks
+      # Hook to allow adding commands to the console UI.
+      #
+      # @param [Usmu::Ui::Console] ui The UI instance for this session.
+      # @param [Commander::Runner] c The Commander instance to add commands to.
+      def commands(ui, c); end
+    end
+  end
+end

data/lib/usmu/site_generator.rb

@@ -58,20 +58,28 @@ module Usmu
       @log.info("Destination: #{@configuration.destination_path}")
       @log.info('')
 
-      renderables.each do |page|
-        @log.success("creating #{page.output_filename}...")
-        @log.debug("Rendering #{page.output_filename} from #{page.name}")
-        file = File.join(@configuration.destination_path, page.output_filename)
-        directory = File.dirname(file)
+      renderables.each &method(:generate_page)
+      nil
+    end
 
-        unless File.directory?(directory)
-          FileUtils.mkdir_p(directory)
-        end
+    private
 
-        File.write file, page.render
-        FileUtils.touch file, :mtime => File.stat(page.input_path).mtime
+    # Helper function to generate a page
+    #
+    # @param [Usmu::Template::Page] page
+    def generate_page(page)
+      output_filename = page.output_filename
+      @log.success("creating #{output_filename}...")
+      @log.debug("Rendering #{output_filename} from #{page.name}")
+      file = File.join(@configuration.destination_path, output_filename)
+      directory = File.dirname(file)
+
+      unless File.directory?(directory)
+        FileUtils.mkdir_p(directory)
       end
-      nil
+
+      File.write file, page.render
+      FileUtils.touch file, :mtime => File.stat(page.input_path).mtime
     end
   end
 end

data/lib/usmu/template/helpers.rb

@@ -1,14 +1,26 @@
-# We really should include this, but it causes an include loop and Include has a strict dependency on Layout due to
-# the inheritance structure. Oh well. Perhaps I'll think of something later.
-#require 'usmu/template/include'
 
 module Usmu
+  # This module is a namespace for all the different types of templates in use by Usmu. It has no functionality
+  # attached to it directly.
   module Template
+    # Helper functions that get imported into the local scope of templates
     class Helpers
+      # Create a new Helpers instance. These are created on demand as needed by templates, there is not a singleton
+      # instance.
       def initialize(configuration)
         @configuration = configuration
       end
 
+      # Finds and renders a named include.
+      #
+      # @param [String] name
+      #   The name of the include file. Should not include file extension.
+      # @param [Hash] args
+      #   The named arguments to provide to the include file. These are incorporated as additional
+      #   metadata available to the include file.
+      # @return [String] The rendered file.
+      #
+      # @api template_helpers
       def include(name, args = {})
         inc = Usmu::Template::Include.find_include(@configuration, name)
         inc.arguments = args

data/lib/usmu/template/include.rb

@@ -7,6 +7,8 @@ module Usmu
 
       private
 
+      # Preserved version of the layout metadata logic
+      # @see Usmu::Template::Layout#metadata
       alias :layout_metadata :metadata
 
       public
@@ -79,7 +81,7 @@ module Usmu
         arguments.each do |i, value|
           args[i.class.name == 'String' ? i : i.to_s] = value
         end
-        
+
         {'site' => @configuration}.deep_merge!(metadata).deep_merge!(args).deep_merge!(variables)
       end
     end

data/lib/usmu/template/layout.rb

@@ -142,7 +142,10 @@ module Usmu
         @layout_history = @layout_history || {}
         @layout_history[configuration] = @layout_history[configuration] || {}
         if @layout_history[configuration][name]
-          Logging.logger[self].debug("Layout loop detected. Current loaded layouts: #{@layout_history[configuration].inspect}")
+          Logging.logger[self].debug(
+              'Layout loop detected. Current loaded layouts: ' +
+              @layout_history[configuration].inspect
+          )
           return nil
         else
           Logging.logger[self].debug("Loading layout '#{name}'")

data/lib/usmu/ui/console.rb

@@ -17,18 +17,10 @@ module Usmu
         @configuration || load_configuration('usmu.yml')
       end
 
+      # @param [Array<String>] args Command line arguments, ie. ARGV.
       def initialize(args)
         @log = Logging.logger[self]
-        @commander = Commander::Runner.new args
-
-        @commander.program :version, Usmu::VERSION
-        @commander.program :description, 'Static site generator powered by Tilt'
-        @commander.program :int_message, 'Interrupt received, closing...'
-
-        @commander.global_option('-v', '--verbose') { Usmu.verbose_logging }
-        @commander.global_option('-q', '--quiet') { Usmu.quiet_logging }
-        @commander.global_option('--log STRING', String) {|log| Usmu.add_file_logger(log) }
-        @commander.global_option('--config STRING', String, &method(:load_configuration))
+        @commander = initialize_commander(args)
 
         Usmu.plugins.load_plugins
         Usmu.plugins.invoke :commands, self, @commander
@@ -54,6 +46,25 @@ module Usmu
         end
         @configuration
       end
+
+      private
+
+      # Helper function to setup a Commander runner
+      # @return [Commander::Runner]
+      def initialize_commander(args)
+        commander = Commander::Runner.new args
+
+        commander.program :version, Usmu::VERSION
+        commander.program :description, 'Static site generator powered by Tilt'
+        commander.program :int_message, 'Interrupt received, closing...'
+
+        commander.global_option('-v', '--verbose') { Usmu.verbose_logging }
+        commander.global_option('-q', '--quiet') { Usmu.quiet_logging }
+        commander.global_option('--log STRING', String) {|log| Usmu.add_file_logger(log) }
+        commander.global_option('--config STRING', String, &method(:load_configuration))
+
+        commander
+      end
     end
   end
 end

data/lib/usmu/version.rb

@@ -1,5 +1,5 @@
 
 module Usmu
   # The current version string for the gem
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

data/test/spec/configuration_spec.rb

@@ -158,4 +158,19 @@ RSpec.describe Usmu::Configuration do
       expect(@configuration.source_files).to eq(%w(index.md test/foo.md))
     end
   end
+
+  it 'should allow indexing the configuration file' do
+    configuration = Usmu::Configuration.from_hash({test: 'foo'})
+    expect(configuration[:test]).to eq('foo')
+  end
+
+  it 'should allow indexing the configuration file with a default value' do
+    configuration = Usmu::Configuration.from_hash({test: 'foo'})
+    expect(configuration[:bar, default: 'baz']).to eq('baz')
+  end
+
+  it 'should allow indexing the configuration file using a path of indices' do
+    configuration = Usmu::Configuration.from_hash({test: {bar: 'foo'}})
+    expect(configuration[:test, :bar]).to eq('foo')
+  end
 end

data/usmu-jruby.gemspec

@@ -38,4 +38,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'guard', '~> 2.8'
   spec.add_development_dependency 'guard-rspec', '~> 4.3'
   spec.add_development_dependency 'turnip', '~> 1.2'
+  spec.add_development_dependency 'sass', '~> 3.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usmu
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Matthew Scharley
@@ -279,11 +279,11 @@ files:
 - README.md
 - Rakefile
 - bin/usmu
-- cucumber.yml
 - lib/usmu.rb
 - lib/usmu/configuration.rb
 - lib/usmu/plugin.rb
 - lib/usmu/plugin/core.rb
+- lib/usmu/plugin/core_hooks.rb
 - lib/usmu/site_generator.rb
 - lib/usmu/template/helpers.rb
 - lib/usmu/template/include.rb

data/cucumber.yml

@@ -1,2 +0,0 @@
----
-default: test/features --format pretty