woody 0.0.12 → 0.0.13

data/lib/woody/compiler.rb

@@ -1,5 +1,8 @@
 module Woody
+  # Handles functions related to compiling the Woody site
   module Compiler
+
+    # Compiles the Woody site
     def self.compile()
       puts "Compiling..."
       meta = YAML.load_file("content/metadata.yml")
@@ -101,6 +104,9 @@ module Woody
 
     private
 
+    # Deletes old files from the site's output directory
+    # @param [Array]  touchedfiles specifies which files to keep
+    # @param [String] subdir specifies a subdirectory of output/ to work in (used for recursion)
     def self.purge_output(touchedfiles, subdir = "")
       Dir.foreach("output/#{subdir}") do |item|
         next if item == '.' or item == '..'

data/lib/woody/deployer.rb

@@ -1,5 +1,7 @@
 module Woody
+  # Handles functions relating to deploying the Woody site
   module Deployer
+    # Deploys the Woody site to S3
     def self.deploy
       touchedfiles = Array.new
       deploy_r touchedfiles
@@ -23,6 +25,8 @@ module Woody
       end
     end
 
+    # Deletes old objects from the S3 bucket
+    # @param [Array] touchedfiles specifies the S3 objects to keep
     def self.purge_bucket(touchedfiles)
       bucket = AWS::S3::Bucket.find $bucketname
       bucket.objects.each do |object|
@@ -30,6 +34,10 @@ module Woody
       end
     end
 
+    # Generates a hash of a file
+    # Stored in S3 object metadata (x-amz-meta-hash) and used to avoid re-uploading unchanged files
+    # @param  [String] filepath path to file
+    # @return [String] hash of file
     def self.filehash(filepath)
       sha1 = Digest::SHA1.new
       File.open(filepath) do|file|
@@ -43,6 +51,12 @@ module Woody
       return sha1.to_s
     end
 
+    # Uploads a file to S3
+    # Sets x-amz-meta-hash to hash generated by Woody::Generator.filehash and checks this
+    # before uploading to avoid resending unchanged data
+    # Prints notices to STDOUT
+    # @param [String] objectname specifies the S3 object's key/name
+    # @param [String] filepath specifies the path to the file to upload
     def self.upload(objectname, filepath)
       # Generate hash of file
       hash = filehash filepath

data/lib/woody/episode.rb

@@ -1,53 +1,70 @@
 module Woody
+  # Represents an episode of the podcast
   class Episode
+    # Creates a new Episode object from segment of metadata.yml
+    # @param  [String] filename specifies the name of the MP3 file
+    # @param  [Hash] meta is the relevant part of metadata.yml
+    # @return [Episode] the new Episode object
     def self.new_from_meta(filename, meta)
       return Episode.new(filename, meta['title'], Date.parse(meta['date']), meta['synopsis'], meta['subtitle'], meta['tags'])
     end
 
-    def initialize(filename, title, date, synopsis, subtitle = nil, tags = [], compiledname = nil)
+    # Creates a new Episode object
+    # @param  [String] filename specifies the name of the MP3 file
+    # @param  [String] title specifies the episode's title
+    # @param  [Date]   date specifies the episode's published date
+    # @param  [String] synopsis specifies the episode's synopsis
+    # @param  [String] subtitle specifies the episode's subtitle
+    # @param  [Array]  tags specifies the episode's tags - each element is a String
+    # @return [Episode] the new Episode object
+    def initialize(filename, title, date, synopsis, subtitle = nil, tags = [])
       @filename = filename
       @title = title
       @date = date
       @synopsis = synopsis
       @subtitle = subtitle
       @tags = tags
-      @compiledname = compiledname
-
-      if @compiledname.nil? or @compiledname.empty?
-        @compiledname = @filename.gsub(/[^0-9A-Za-z .]/, '').gsub(' ', '_')
-      end
+      @compiledname = @filename.gsub(/[^0-9A-Za-z .]/, '').gsub(' ', '_')
     end
 
     attr_accessor :filename, :title, :date, :synopsis, :tags, :subtitle, :compiledname
 
+    # @return the episode's page URL where possible, otherwise false
     def url
-      return "#{$config['urlbase']}#{path}" unless path.nil?
+      return "#{$config['urlbase']}#{path}" unless path == false
       return false
     end
 
+    # @return the episode's page path where possible, otherwise false
     def path(leader=true)
       return "#{leader ? "/" : ""}episode/#{@compiledname[0..-5]}.html" unless @compiledname.nil?
       return false
     end
 
+    # @return the episode's media file URL where possible, otherwise false
     def file_url
-      return "#{$config['urlbase']}#{file_path}" unless file_path.nil?
+      return "#{$config['urlbase']}#{file_path}" unless file_path == false
       return false
     end
 
+    # @return the episode's media file path where possible, otherwise false
     def file_path(leader=true)
       return "#{leader ? "/" : ""}assets/mp3/#{@compiledname}" unless @compiledname.nil?
       return false
     end
 
+    # @return [String] a comma separated list of tags, or nil if no tags
     def keywords
       @tags.join ', ' unless @tags.nil? or @tags.empty?
     end
 
+    # @return [Integer] the size of the episodes media file in bytes
     def size
       File.size "content/#{filename}"
     end
 
+    # TODO: fix this!
+    # @return [String] the duration of the media file, formatted as minutes:seconds
     def duration
       return @duration unless @duration.nil?
       length = 0
@@ -56,7 +73,7 @@ module Woody
       end
       length = length.to_i
       seconds = length % 60
-      minutes = (length / 60).to_i
+      minutes = (length / 60).floor
       @duration = "#{minutes}:#{seconds}"
     end
 

data/lib/woody/generator.rb

@@ -1,5 +1,9 @@
 module Woody
+  # Handles functions related to generating Woody sites and updating them and their data stores
   module Generator
+    # Generates a blank skeleton Woody site
+    # Do not call Woody::init before this!
+    # @param [String] name specifies the relative directory to create the new site in.
     def self.new_site(name)
       puts "Creating new site '#{name}'..."
       if File.directory?(name)
@@ -31,6 +35,7 @@ module Woody
       puts "Now, do `cd #{name}` then edit the config file, woody-config.yml."
     end
 
+    # Replaces the templates in the Woody site with the gem's current default ones
     def self.update_templates
       puts "Updating templates..."
       cpy_t("layout.html", "templates/layout.html")
@@ -42,10 +47,19 @@ module Woody
 
     private
 
+    # Path of template directory inside gem
+    $source_root = File.expand_path("../../templates", __FILE__)
+
+    # Creates a directory and its parents if necessary, outputting a notice to STDOUT
+    # @param [String] dir specifies the directory to create
     def self.cdir_p(dir)
       puts "Creating directory '#{dir}'"
       FileUtils.mkdir_p(dir)
     end
+
+    # Copies a file from inside the gem's template directory, to a location in the current Woody site., outputting a notice to STDOUT.
+    # @param [String] source specificies the source file (inside the gem's internal template directory)
+    # @param [String] destination specidies the destination (inside the Woody site's root directory)
     def self.cpy_t(source, destination)
       puts "Creating file '#{destination}'"
       FileUtils.cp File.join($source_root, source), destination

data/lib/woody/version.rb

@@ -1,3 +1,4 @@
 module Woody
-  VERSION = "0.0.12"
+  # Specifies Woody gem version
+  VERSION = "0.0.13"
 end

data/lib/woody.rb

@@ -15,10 +15,10 @@ oldverbosity = $VERBOSE; $VERBOSE = nil # Silence depreciation notice
 require 'mp3info'
 $VERBOSE = oldverbosity
 
-
+# Woody podcast static site generator
 module Woody
-  $source_root = File.expand_path("../../templates", __FILE__)
-  # Load configuration
+
+  # Load configuration and connect to S3
   def self.init
     begin
       $config = YAML.load_file("woody-config.yml")
@@ -49,10 +49,16 @@ module Woody
 
 end
 
-def link_to(name, url)
-  return %Q{<a href="#{url}">#{name}</a>}
+
+# Generates HTML hyperlink/anchor tag
+# @param  [String] text specifies text to display for link
+# @param  [String] url specifies URL/path to link to
+# @return [String] generated HTML anchor tag (hyperlink)
+def link_to(text, url)
+  return %Q{<a href="#{url}">#{text}</a>}
 end
 
+# @return HTML meta generator tag with Woody attribution and version
 def generator_meta_tag()
   return %Q{<meta name="generator" content="Woody #{Woody::VERSION}" />}
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: woody
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.13
   prerelease: 
 platform: ruby
 authors: