Skip to content
Browse files

TomDoc some things.

  • Loading branch information...
1 parent 155cbd1 commit a428acec1c41eaee206f36fc2fdb41a0479bee60 @mojombo mojombo committed
Showing with 107 additions and 36 deletions.
  1. +52 −0 lib/jekyll/filters.rb
  2. +18 −10 lib/jekyll/layout.rb
  3. +37 −26 lib/jekyll/page.rb
View
52 lib/jekyll/filters.rb
@@ -3,18 +3,43 @@
module Jekyll
module Filters
+ # Convert a Textile string into HTML output.
+ #
+ # input - The Textile String to convert.
+ #
+ # Returns the HTML formatted String.
def textilize(input)
TextileConverter.new.convert(input)
end
+ # Format a date in short format e.g. "27 Jan 2011".
+ #
+ # date - the Time to format.
+ #
+ # Returns the formatting String.
def date_to_string(date)
date.strftime("%d %b %Y")
end
+ # Format a date in long format e.g. "27 January 2011".
+ #
+ # date - The Time to format.
+ #
+ # Returns the formatted String.
def date_to_long_string(date)
date.strftime("%d %B %Y")
end
+ # Format a date for use in XML.
+ #
+ # date - The Time to format.
+ #
+ # Examples
+ #
+ # date_to_xmlschema(Time.now)
+ # # => "2011-04-24T20:34:46+08:00"
+ #
+ # Returns the formatted String.
def date_to_xmlschema(date)
date.xmlschema
end
@@ -23,6 +48,17 @@ def xml_escape(input)
CGI.escapeHTML(input)
end
+ # CGI escape a string for use in a URL. Replaces any special characters
+ # with appropriate %XX replacements.
+ #
+ # input - The String to escape.
+ #
+ # Examples
+ #
+ # cgi_escape('foo,bar;baz?')
+ # # => "foo%2Cbar%3Bbaz%3F"
+ #
+ # Returns the escaped String.
def cgi_escape(input)
CGI::escape(input)
end
@@ -31,10 +67,26 @@ def uri_escape(input)
URI.escape(input)
end
+ # Count the number of words in the input string.
+ #
+ # input - The String on which to operate.
+ #
+ # Returns the Integer word count.
def number_of_words(input)
input.split.length
end
+ # Join an array of things into a string by separating with commes and the
+ # word "and" for the last one.
+ #
+ # array - The Array of Strings to join.
+ #
+ # Examples
+ #
+ # array_to_sentence_string(["apples", "oranges", "grapes"])
+ # # => "apples, oranges, and grapes"
+ #
+ # Returns the formatted String.
def array_to_sentence_string(array)
connector = "and"
case array.length
View
28 lib/jekyll/layout.rb
@@ -3,16 +3,23 @@ module Jekyll
class Layout
include Convertible
- attr_accessor :site
+ # Gets the Site object.
+ attr_reader :site
+
+ # Gets/Sets the extension of this layout.
attr_accessor :ext
- attr_accessor :data, :content
+
+ # Gets/Sets the Hash that holds the metadata for this layout.
+ attr_accessor :data
+
+ # Gets/Sets the content of this layout.
+ attr_accessor :content
# Initialize a new Layout.
- # +site+ is the Site
- # +base+ is the String path to the <source>
- # +name+ is the String filename of the post file
#
- # Returns <Page>
+ # site - The Site.
+ # base - The String path to the source.
+ # name - The String filename of the post file.
def initialize(site, base, name)
@site = site
@base = base
@@ -24,13 +31,14 @@ def initialize(site, base, name)
self.read_yaml(base, name)
end
- # Extract information from the layout filename
- # +name+ is the String filename of the layout file
+ # Extract information from the layout filename.
+ #
+ # name - The String filename of the layout file.
#
- # Returns nothing
+ # Returns nothing.
def process(name)
self.ext = File.extname(name)
end
end
-end
+end
View
63 lib/jekyll/page.rb
@@ -8,12 +8,11 @@ class Page
attr_accessor :data, :content, :output
# Initialize a new Page.
- # +site+ is the Site
- # +base+ is the String path to the <source>
- # +dir+ is the String path between <source> and the file
- # +name+ is the String filename of the file
#
- # Returns <Page>
+ # site - The Site object.
+ # base - The String path to the source.
+ # dir - The String path between the source and the file.
+ # name - The String filename of the file.
def initialize(site, base, dir, name)
@site = site
@base = base
@@ -26,22 +25,24 @@ def initialize(site, base, dir, name)
# The generated directory into which the page will be placed
# upon generation. This is derived from the permalink or, if
- # permalink is absent, set to '/'
+ # permalink is absent, we be '/'
#
- # Returns <String>
+ # Returns the String destination directory.
def dir
url[-1, 1] == '/' ? url : File.dirname(url)
end
- # The full path and filename of the post.
- # Defined in the YAML of the post body
- # (Optional)
+ # The full path and filename of the post. Defined in the YAML of the post
+ # body.
#
- # Returns <String>
+ # Returns the String permalink or nil if none has been set.
def permalink
self.data && self.data['permalink']
end
+ # The template of the permalink.
+ #
+ # Returns the template String.
def template
if self.site.permalink_style == :pretty && !index? && html?
"/:basename/"
@@ -50,10 +51,9 @@ def template
end
end
- # The generated relative url of this page
- # e.g. /about.html
+ # The generated relative url of this page. e.g. /about.html.
#
- # Returns <String>
+ # Returns the String url.
def url
return @url if @url
@@ -74,20 +74,22 @@ def url
@url
end
- # Extract information from the page filename
- # +name+ is the String filename of the page file
+ # Extract information from the page filename.
+ #
+ # name - The String filename of the page file.
#
- # Returns nothing
+ # Returns nothing.
def process(name)
self.ext = File.extname(name)
self.basename = name[0 .. -self.ext.length-1]
end
# Add any necessary layouts to this post
- # +layouts+ is a Hash of {"name" => "layout"}
- # +site_payload+ is the site payload hash
#
- # Returns nothing
+ # layouts - The Hash of {"name" => "layout"}.
+ # site_payload - The site payload Hash.
+ #
+ # Returns nothing.
def render(layouts, site_payload)
payload = {
"page" => self.to_liquid,
@@ -97,27 +99,33 @@ def render(layouts, site_payload)
do_layout(payload, layouts)
end
+ # Convert this Page's data to a Hash suitable for use by Liquid.
+ #
+ # Returns the Hash representation of this Page.
def to_liquid
self.data.deep_merge({
"url" => File.join(@dir, self.url),
"content" => self.content })
end
-
+
# Obtain destination path.
- # +dest+ is the String path to the destination dir
#
- # Returns destination file path.
+ # dest - The String path to the destination dir.
+ #
+ # Returns the destination file path String.
def destination(dest)
- # The url needs to be unescaped in order to preserve the correct filename
+ # The url needs to be unescaped in order to preserve the correct
+ # filename.
path = File.join(dest, @dir, CGI.unescape(self.url))
path = File.join(path, "index.html") if self.url =~ /\/$/
path
end
# Write the generated page file to the destination directory.
- # +dest+ is the String path to the destination dir
#
- # Returns nothing
+ # dest - The String path to the destination dir.
+ #
+ # Returns nothing.
def write(dest)
path = destination(dest)
FileUtils.mkdir_p(File.dirname(path))
@@ -126,14 +134,17 @@ def write(dest)
end
end
+ # Returns the object as a debug String.
def inspect
"#<Jekyll:Page @name=#{self.name.inspect}>"
end
+ # Returns the Boolean of whether this Page is HTML or not.
def html?
output_ext == '.html'
end
+ # Returns the Boolean of whether this Page is an index file or not.
def index?
basename == 'index'
end

0 comments on commit a428ace

Please sign in to comment.
Something went wrong with that request. Please try again.