From b08ae549932520b55efd4d16068c6226438d7caa Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 23 Nov 2009 13:48:06 -0800 Subject: [PATCH 1/6] Fix the yardoc link in the README. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9120183e..27490349 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Then any Sass files in `public/stylesheets/sass` will be compiled CSS files in `public/stylesheets` on every request. To use Haml and Sass programatically, -check out the [YARD documentation](http://haml-lang.com/docs/yardoc). +check out the [YARD documentation](http://haml-lang.com/docs/yardoc/). ## Formatting From cb045613859bd19c96652ccc8a71824da03ccdfb Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 23 Nov 2009 13:44:31 -0800 Subject: [PATCH 2/6] Update to the latest YARD. --- Rakefile | 6 +++--- haml.gemspec | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Rakefile b/Rakefile index 98e35517..63565cb4 100644 --- a/Rakefile +++ b/Rakefile @@ -235,11 +235,11 @@ begin files = FileList.new('doc-src/*').to_a.sort_by {|s| s.size} + %w[MIT-LICENSE VERSION] t.options << '--files' << files.join(',') end - Rake::Task['yardoc'].instance_variable_set('@comment', nil) + Rake::Task['yard'].instance_variable_set('@comment', nil) desc "Generate Documentation" - task :doc => :yardoc - task :redoc => :yardoc + task :doc => :yard + task :redoc => :yard rescue LoadError desc "Generate Documentation" task :doc => :rdoc diff --git a/haml.gemspec b/haml.gemspec index d4885c44..d9c6e745 100644 --- a/haml.gemspec +++ b/haml.gemspec @@ -22,7 +22,7 @@ HAML_GEMSPEC = Gem::Specification.new do |spec| but it can function as a stand-alone templating engine. END - spec.add_development_dependency 'yard', '>= 0.2.3' + spec.add_development_dependency 'yard', '>= 0.4.0' spec.add_development_dependency 'maruku', '>= 0.5.9' # We need the revision file to exist, From 6d887f78ae1e90b8cc74131f7ec9d64a3a88d16f Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 23 Nov 2009 14:01:16 -0800 Subject: [PATCH 3/6] Update the custom YARD CSS to use the proper YARD methodology. --- Rakefile | 13 ++++++++++++ yard/default/.gitignore | 1 + .../fulldoc/html/css/common.sass} | 0 yard/full_doc_mods.rb | 20 ------------------- 4 files changed, 14 insertions(+), 20 deletions(-) create mode 100644 yard/default/.gitignore rename yard/{haml-style.sass => default/fulldoc/html/css/common.sass} (100%) delete mode 100644 yard/full_doc_mods.rb diff --git a/Rakefile b/Rakefile index 63565cb4..aae0a179 100644 --- a/Rakefile +++ b/Rakefile @@ -225,6 +225,17 @@ end begin require 'yard' + namespace :yard do + task :sass do + require File.dirname(__FILE__) + '/lib/sass' + Dir[File.dirname(__FILE__) + "/yard/default/**/*.sass"].each do |sass| + File.open(sass.gsub(/sass$/, 'css'), 'w') do |f| + f.write(Sass::Engine.new(File.read(sass)).render) + end + end + end + end + YARD::Rake::YardocTask.new do |t| t.files = FileList.new('lib/**/*.rb') do |list| list.exclude('lib/haml/template/*.rb') @@ -234,7 +245,9 @@ begin t.options += FileList.new('yard/*.rb').to_a.map {|f| ['-e', f]}.flatten files = FileList.new('doc-src/*').to_a.sort_by {|s| s.size} + %w[MIT-LICENSE VERSION] t.options << '--files' << files.join(',') + t.options << '--template-path' << File.dirname(__FILE__) + '/yard' end + Rake::Task['yard'].prerequisites.insert(0, 'yard:sass') Rake::Task['yard'].instance_variable_set('@comment', nil) desc "Generate Documentation" diff --git a/yard/default/.gitignore b/yard/default/.gitignore new file mode 100644 index 00000000..b3a52671 --- /dev/null +++ b/yard/default/.gitignore @@ -0,0 +1 @@ +*.css diff --git a/yard/haml-style.sass b/yard/default/fulldoc/html/css/common.sass similarity index 100% rename from yard/haml-style.sass rename to yard/default/fulldoc/html/css/common.sass diff --git a/yard/full_doc_mods.rb b/yard/full_doc_mods.rb deleted file mode 100644 index 243baae1..00000000 --- a/yard/full_doc_mods.rb +++ /dev/null @@ -1,20 +0,0 @@ -require File.dirname(__FILE__) + "/../lib/sass" - -class YARD::Generators::FullDocGenerator - protected - - def generate_assets_with_haml - generate_assets_without_haml - - if format == :html && serializer - template_file = find_template template_path(css_file) - haml_style = Sass::Engine.new(File.read( - File.dirname(__FILE__) + "/haml-style.sass")).render - serializer.serialize(css_file, File.read(template_file) + haml_style) - end - - true - end - alias_method :generate_assets_without_haml, :generate_assets - alias_method :generate_assets, :generate_assets_with_haml -end From 490d7155898827aaf294476063e7b4a32e66792a Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 23 Nov 2009 14:24:53 -0800 Subject: [PATCH 4/6] Make the docstrings YARD 0.4 compatible. --- lib/haml/precompiler.rb | 42 ++++++++++++++++++++-------------------- lib/sass/engine.rb | 6 +++--- lib/sass/script/color.rb | 14 ++++---------- lib/sass/script/lexer.rb | 8 ++++---- 4 files changed, 32 insertions(+), 38 deletions(-) diff --git a/lib/haml/precompiler.rb b/lib/haml/precompiler.rb index 5725f2b4..dd461450 100644 --- a/lib/haml/precompiler.rb +++ b/lib/haml/precompiler.rb @@ -10,10 +10,10 @@ module Haml # Designates an XHTML/XML element. ELEMENT = ?% - # Designates a
element with the given class. + # Designates a `
` element with the given class. DIV_CLASS = ?. - # Designates a
element with the given id. + # Designates a `
` element with the given id. DIV_ID = ?# # Designates an XHTML/XML comment. @@ -77,7 +77,7 @@ module Haml # - else # %p no! # - # The block is ended after %p no!, because else + # The block is ended after `%p no!`, because `else` # is a member of this array. MID_BLOCK_KEYWORD_REGEX = /^-\s*(#{%w[else elsif rescue ensure when end].join('|')})\b/ @@ -201,7 +201,7 @@ END # Processes a single line of Haml. # # This method doesn't return anything; it simply processes the line and - # adds the appropriate code to @precompiled. + # adds the appropriate code to `@precompiled`. def process_line(text, index) @index = index + 1 @@ -278,7 +278,7 @@ END text[MID_BLOCK_KEYWORD_REGEX, 1] end - # Evaluates text in the context of the scope object, but + # Evaluates `text` in the context of the scope object, but # does not output the result. def push_silent(text, can_suppress = false) flush_merged_text @@ -286,7 +286,7 @@ END @precompiled << "#{text};" end - # Adds text to @buffer with appropriate tabulation + # Adds `text` to `@buffer` with appropriate tabulation # without parsing it. def push_merged_text(text, tab_change = 0, indent = true) text = !indent || @dont_indent_next_line || @options[:ugly] ? text : "#{' ' * @output_tabs}#{text}" @@ -294,7 +294,7 @@ END @dont_indent_next_line = false end - # Concatenate text to @buffer without tabulation. + # Concatenate `text` to `@buffer` without tabulation. def concat_merged_text(text) @to_merge << [:text, text, 0] end @@ -347,18 +347,18 @@ END end end - # Adds +text+ to @buffer while flattening text. + # Adds +text+ to `@buffer` while flattening text. def push_flat(line) text = line.full.dup text = "" unless text.gsub!(/^#{@flat_spaces}/, '') @filter_buffer << "#{text}\n" end - # Causes text to be evaluated in the context of - # the scope object and the result to be added to @buffer. + # Causes `text` to be evaluated in the context of + # the scope object and the result to be added to `@buffer`. # - # If opts[:preserve_script] is true, Haml::Helpers#find_and_flatten is run on - # the result before it is added to @buffer + # If `opts[:preserve_script]` is true, Haml::Helpers#find_and_flatten is run on + # the result before it is added to `@buffer` def push_script(text, opts = {}) raise SyntaxError.new("There's no Ruby code for = to evaluate.") if text.empty? return if options[:suppress_eval] @@ -391,7 +391,7 @@ END !(opts[:in_tag] || opts[:nuke_inner_whitespace] || @options[:ugly])]) end - # Causes text to be evaluated, and Haml::Helpers#find_and_flatten + # Causes `text` to be evaluated, and Haml::Helpers#find_and_flatten # to be run on it afterwards. def push_flat_script(text, options = {}) flush_merged_text @@ -407,13 +407,13 @@ END push_and_tabulate([:haml_comment]) end - # Closes the most recent item in @to_close_stack. + # Closes the most recent item in `@to_close_stack`. def close tag, *rest = @to_close_stack.pop send("close_#{tag}", *rest) end - # Puts a line in @precompiled that will add the closing tag of + # Puts a line in `@precompiled` that will add the closing tag of # the most recently opened tag. def close_element(value) tag, nuke_outer_whitespace, nuke_inner_whitespace = value @@ -465,8 +465,8 @@ END @template_tabs -= 1 end - # Iterates through the classes and ids supplied through . - # and # syntax, and returns a hash with them as attributes, + # Iterates through the classes and ids supplied through `.` + # and `#` syntax, and returns a hash with them as attributes, # that can then be merged with another attributes hash. def parse_class_and_id(list) attributes = {} @@ -663,7 +663,7 @@ END end # Parses a line that will render as an XHTML tag, and adds the code that will - # render that tag to @precompiled. + # render that tag to `@precompiled`. def render_tag(line) tag_name, attributes, attributes_hashes, object_ref, nuke_outer_whitespace, nuke_inner_whitespace, action, value, last_line = parse_tag(line) @@ -794,7 +794,7 @@ END end # Renders a line that creates an XHTML tag and has an implicit div because of - # . or #. + # `.` or `#`. def render_div(line) render_tag('%div' + line) end @@ -982,8 +982,8 @@ END !flat? && @next_line.tabs > @line.tabs end - # Pushes value onto @to_close_stack and increases - # @template_tabs. + # Pushes value onto `@to_close_stack` and increases + # `@template_tabs`. def push_and_tabulate(value) @to_close_stack.push(value) @template_tabs += 1 diff --git a/lib/sass/engine.rb b/lib/sass/engine.rb index 1b2dcf08..ae3b0ecb 100644 --- a/lib/sass/engine.rb +++ b/lib/sass/engine.rb @@ -106,15 +106,15 @@ module Sass # Includes named mixin declared using MIXIN_DEFINITION_CHAR MIXIN_INCLUDE_CHAR = ?+ - # The regex that matches properties of the form name: prop. + # The regex that matches properties of the form `name: prop`. PROPERTY_NEW_MATCHER = /^[^\s:"\[]+\s*[=:](\s|$)/ # The regex that matches and extracts data from - # properties of the form name: prop. + # properties of the form `name: prop`. PROPERTY_NEW = /^([^\s=:"]+)(\s*=|:)(?:\s+|$)(.*)/ # The regex that matches and extracts data from - # properties of the form :name prop. + # properties of the form `:name prop`. PROPERTY_OLD = /^:([^\s=:"]+)\s*(=?)(?:\s+|$)(.*)/ # The default options for Sass::Engine. diff --git a/lib/sass/script/color.rb b/lib/sass/script/color.rb index 5468feff..010264ae 100644 --- a/lib/sass/script/color.rb +++ b/lib/sass/script/color.rb @@ -5,7 +5,7 @@ module Sass::Script class Color < Literal class << self; include Haml::Util; end - # A hash from color names to [red, green, blue] value arrays. + # A hash from color names to `[red, green, blue]` value arrays. HTML4_COLORS = map_vals({ 'black' => 0x000000, 'silver' => 0xc0c0c0, @@ -24,7 +24,7 @@ module Sass::Script 'teal' => 0x008080, 'aqua' => 0x00ffff }) {|color| (0..2).map {|n| color >> (n << 3) & 0xff}.reverse} - # A hash from [red, green, blue] value arrays to color names. + # A hash from `[red, green, blue]` value arrays to color names. HTML4_COLORS_REVERSE = map_hash(HTML4_COLORS) {|k, v| [v, k]} # Creates a new color from RGB components. @@ -135,10 +135,7 @@ END # {Color} # : Multiplies each of the RGB color channels together. # - # {Literal} - # : See {Literal#times}. - # - # @param other [Literal] The right-hand side of the operator + # @param other [Number, Color] The right-hand side of the operator # @return [Color] The resulting color # @raise [Sass::SyntaxError] if `other` is a number with units def times(other) @@ -181,10 +178,7 @@ END # {Color} # : Takes each of this color's RGB color channels modulo the other color's. # - # {Literal} - # : See {Literal#mod}. - # - # @param other [Literal] The right-hand side of the operator + # @param other [Number, Color] The right-hand side of the operator # @return [Color] The resulting color # @raise [Sass::SyntaxError] if `other` is a number with units def mod(other) diff --git a/lib/sass/script/lexer.rb b/lib/sass/script/lexer.rb index 083065f4..268331e2 100644 --- a/lib/sass/script/lexer.rb +++ b/lib/sass/script/lexer.rb @@ -8,16 +8,16 @@ module Sass class Lexer # A struct containing information about an individual token. # - # `type`: [{Symbol}] + # `type`: \[{Symbol}\] # : The type of token. # - # `value`: [{Object}] + # `value`: \[{Object}\] # : The Ruby object corresponding to the value of the token. # - # `line`: [{Fixnum}] + # `line`: \[{Fixnum}\] # : The line of the source file on which the token appears. # - # `offset`: [{Fixnum}] + # `offset`: \[{Fixnum}\] # : The number of bytes into the line the SassScript token appeared. Token = Struct.new(:type, :value, :line, :offset) From 8037a958b1bc70138d754536253b8765ffca18e4 Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 23 Nov 2009 14:53:43 -0800 Subject: [PATCH 5/6] Make the custom YARD CSS work with the new YARD HTML. --- yard/default/fulldoc/html/css/common.sass | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/yard/default/fulldoc/html/css/common.sass b/yard/default/fulldoc/html/css/common.sass index 98927d99..2cb3940f 100644 --- a/yard/default/fulldoc/html/css/common.sass +++ b/yard/default/fulldoc/html/css/common.sass @@ -9,7 +9,7 @@ float: none margin: 0 2em -.section.readme +#filecontents *:target, dt:target + dd background-color: #ccf border: 1px solid #88b From 53e4668775c8f0452679f37d109ec80caf1d5fb6 Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Mon, 23 Nov 2009 15:03:48 -0800 Subject: [PATCH 6/6] Add a custom YARD footer for Google Analytics. --- yard/default/layout/html/footer.erb | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 yard/default/layout/html/footer.erb diff --git a/yard/default/layout/html/footer.erb b/yard/default/layout/html/footer.erb new file mode 100644 index 00000000..42d9cde0 --- /dev/null +++ b/yard/default/layout/html/footer.erb @@ -0,0 +1,12 @@ +<%= superb :footer %> +<% if ENV["ANALYTICS"] %> + + +<% end %>