yard-docco 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+=== 1.0.0 / 2011-07-31
+
+* Initial Release

data/README.md

@@ -0,0 +1,84 @@
+YARD-Docco: Docco style code annotation
+====================================
+
+Synopsis
+--------
+
+YARD-Docco is a YARD extension that provides an additional source view that
+will show comments alongside the source code within a method. I recently spent
+some time learning Backbone.js and really enjoyed the annotated source code that
+was generated for a large number of the examples and thought that it would be 
+useful to add this view to YARD's existing source view to take advantage of comments
+made within methods.
+
+Examples
+--------
+
+I have created a trivial, example project to help provide a quick 
+visualization of the resulting documentation.
+
+The implemented example has been deployed at [http://recursivegames.com/yard-docco](http://recursivegames.com/yard-docco).
+
+**1. Comments made within methods appear alongside the code they are attempting to describe.
+
+**2. YARD tags (e.g. @note, @todo) and links will appear as they do for methods and classes.
+
+Installation
+------------
+
+YARD-Docco requires the following gems installed:
+
+    YARD 0.7.0 - http://yardoc.org
+
+To install `yard-docco` use the following command:
+
+    $ gem install yard-docco
+
+(Add `sudo` if you're installing under a POSIX system as root)
+
+Usage
+-----
+
+YARD supports for automatically including gems with the prefix `yard-` 
+as a plugin. To enable automatic loading yard-docco. 
+
+    $ yard config load_plugins true
+    $ yardoc 'example/**/*.rb'
+
+Now you can run YARD as you [normally](https://github.com/lsegal/yard) would and 
+have your features, step definitions and transforms captured.
+
+An example with the rake task:
+
+    require 'yard'
+
+    YARD::Rake::YardocTask.new do |t|
+      t.files   = ['lib/**/*.rb', 'app/**/*.rb']
+      t.options = ['--any', '--extra', '--opts'] # optional
+    end
+
+LICENSE
+-------
+
+(The MIT License)
+
+Copyright (c) 2011 Franklin Webber
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rake'
+
+task :default => :gendoc
+
+task :clean do
+  `rm -rf doc`
+  `rm -rf .yardoc`
+end
+
+task :gendoc => :clean do
+  `yardoc -e ./lib/yard-docco.rb 'example/**/*' --debug`
+  #`open doc/index.html`
+end

data/example/annotated_source.rb

@@ -0,0 +1,252 @@
+class Example
+  
+  def to_s
+    
+    # Comments at the start of will be collected with the comments below and
+    # all notes and todos will be above even this.
+    # @note that I want to tell you something
+    # @todo this is a todo
+    # This sentence was below the @note and the @todo but will appear with the
+    # other sentences below them.
+    self.to_s.capitalize
+    
+    # Some comments at the end that should get included as well
+    
+  end
+  
+  #
+  # Create an xml representation of the specified class based on defined
+  # HappyMapper elements and attributes. The method is defined in a way
+  # that it can be called recursively by classes that are also HappyMapper
+  # classes, allowg for the composition of classes.
+  #
+  # @param [Nokogiri::XML::Builder] builder an instance of the XML builder which
+  #     is being used when called recursively.
+  # @param [String] default_namespace the name of the namespace which is the
+  #     default for the xml being produced; this is specified by the element
+  #     declaration when calling #to_xml recursively.
+  #
+  # @return [String,Nokogiri::XML::Builder] return XML representation of the
+  #      HappyMapper object; when called recursively this is going to return
+  #      and Nokogiri::XML::Builder object.
+  #
+  def to_xml(builder = nil,default_namespace = nil)
+    
+    #
+    # If {#to_xml} has been called without a passed in builder instance that
+    # means we are going to return xml output. When it has been called with
+    # a builder instance that means we most likely being called recursively
+    # and will return the end product as a builder instance. 
+    #
+    unless builder
+      write_out_to_xml = true
+      builder = Nokogiri::XML::Builder.new
+    end
+    
+    #
+    # Find the attributes for the class and collect them into an array
+    # that will be placed into a Hash structure
+    #
+    attributes = self.class.attributes.collect do |attribute|
+      
+      #
+      # If an attribute is marked as read_only then we want to ignore the attribute
+      # when it comes to saving the xml document; so we wiill not go into any of
+      # the below process
+      # 
+      unless attribute.options[:read_only]
+      
+        value = send(attribute.method_name)
+      
+        #
+        # If the attribute defines an on_save lambda/proc or value that maps to 
+        # a method that the class has defined, then call it with the value as a
+        # parameter.
+        #
+        if on_save_action = attribute.options[:on_save]
+          if on_save_action.is_a?(Proc)
+            value = on_save_action.call(value)
+          elsif respond_to?(on_save_action)
+            value = send(on_save_action,value)
+          end
+        end
+      
+        #
+        # Attributes that have a nil value should be ignored unless they explicitly
+        # state that they should be expressed in the output.
+        #
+        if value || attribute.options[:state_when_nil]
+          attribute_namespace = attribute.options[:namespace] || default_namespace
+          [ "#{attribute_namespace ? "#{attribute_namespace}:" : ""}#{attribute.tag}", value ]
+        else
+          []
+        end
+        
+      else
+        []
+      end
+      
+    end.flatten
+    
+    attributes = Hash[ *attributes ]
+  
+    #
+    # Create a tag in the builder that matches the class's tag name and append
+    # any attributes to the element that were defined above.
+    #
+    builder.send(self.class.tag_name,attributes) do |xml|
+      
+      #
+      # Add all the registered namespaces to the root element.
+      # When this is called recurisvely by composed classes the namespaces
+      # are still added to the root element
+      # 
+      # However, we do not want to add the namespace if the namespace is 'xmlns'
+      # which means that it is the default namesapce of the code.
+      #
+      if self.class.instance_variable_get('@registered_namespaces') && builder.doc.root
+        self.class.instance_variable_get('@registered_namespaces').each_pair do |name,href|
+          name = nil if name == "xmlns"
+          builder.doc.root.add_namespace(name,href)
+        end
+      end
+      
+      #
+      # If the object we are persisting has a namespace declaration we will want
+      # to use that namespace or we will use the default namespace.
+      # When neither are specifed we are simply using whatever is default to the
+      # builder
+      #
+      if self.class.respond_to?(:namespace) && self.class.namespace
+        xml.parent.namespace = builder.doc.root.namespace_definitions.find do |x| 
+          x.prefix == self.class.namespace
+        end
+      elsif default_namespace
+        xml.parent.namespace = builder.doc.root.namespace_definitions.find do |x| 
+          x.prefix == default_namespace
+        end
+      end
+  
+      
+      #
+      # When a text_node has been defined we add the resulting value
+      # the output xml
+      #
+      if text_node = self.class.instance_variable_get('@text_node')
+        
+        unless text_node.options[:read_only]
+          text_accessor = text_node.tag || text_node.name
+          value = send(text_accessor)
+        
+          if on_save_action = text_node.options[:on_save]
+            if on_save_action.is_a?(Proc)
+              value = on_save_action.call(value)
+            elsif respond_to?(on_save_action)
+              value = send(on_save_action,value)
+            end
+          end
+        
+          builder.text(value)
+        end
+        
+      end
+  
+      #
+      # for every define element (i.e. has_one, has_many, element) we are
+      # going to persist each one
+      #
+      self.class.elements.each do |element|
+        
+        #
+        # If an element is marked as read only do not consider at all when 
+        # saving to XML.
+        # 
+        unless element.options[:read_only]
+          
+          tag = element.tag || element.name
+          
+          #
+          # The value to store is the result of the method call to the element,
+          # by default this is simply utilizing the attr_accessor defined. However,
+          # this allows for this method to be overridden
+          #
+          value = send(element.name)
+  
+          #
+          # If the element defines an on_save lambda/proc then we will call that
+          # operation on the specified value. This allows for operations to be 
+          # performed to convert the value to a specific value to be saved to the xml.
+          #
+          if on_save_action = element.options[:on_save]
+            if on_save_action.is_a?(Proc)
+              value = on_save_action.call(value)
+            elsif respond_to?(on_save_action)
+              value = send(on_save_action,value)
+            end 
+          end
+  
+          # Normally a nil value would be ignored, however if specified then
+          # an empty element will be written to the xml
+          #
+          if value.nil? && element.options[:single] && element.options[:state_when_nil]
+            xml.send(tag,"")
+          end
+        
+          #
+          # To allow for us to treat both groups of items and singular items
+          # equally we wrap the value and treat it as an array.
+          #
+          if value.nil?
+            values = []
+          elsif value.respond_to?(:to_ary) && !element.options[:single]
+            values = value.to_ary
+          else
+            values = [value]
+          end
+        
+          values.each do |item|
+  
+            if item.is_a?(HappyMapper)
+  
+              #
+              # Other items are convertable to xml through the xml builder
+              # process should have their contents retrieved and attached
+              # to the builder structure
+              #
+              item.to_xml(xml,element.options[:namespace])
+  
+            elsif item
+            
+              item_namespace = element.options[:namespace] || default_namespace
+            
+              #
+              # When a value exists we should append the value for the tag
+              #
+              if item_namespace
+                xml[item_namespace].send(tag,item.to_s)
+              else
+                xml.send(tag,item.to_s)
+              end
+  
+            else
+  
+              #
+              # Normally a nil value would be ignored, however if specified then
+              # an empty element will be written to the xml
+              #
+              xml.send(tag,"") if element.options[:state_when_nil]
+  
+            end
+  
+          end
+          
+        end
+      end
+  
+    end
+  
+    write_out_to_xml ? builder.to_xml : builder
+    
+  end
+
+end

data/lib/yard-docco.rb

@@ -0,0 +1,8 @@
+module DoccoInTheYARD
+  VERSION = '1.0.0'
+end
+
+YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
+
+# The following static paths and templates are for yard server
+YARD::Server.register_static_path File.dirname(__FILE__) + "/../templates/default/fulldoc/html"

data/templates/default/fulldoc/html/css/docco.css

@@ -0,0 +1,37 @@
+
+.annotated_source_code {
+  display: none;
+  border-collapse:collapse;
+}
+
+/* Within the annotated source section the docstring should have a much smaller
+   right margin so that the description text will be closer to the center line */
+.annotated_source_code * div.docstring { margin-right: 20px; }
+
+/* For the comment column set a minimum/max width and change the fonts to look
+   like the nice font and size used by docco comments. Docco examples I have 
+   seen use 450px, I'm going a little smaller here to allow more to appear on
+   screen. */
+.annotated_source_code * td.comment {
+  width: 400px; min-width: 400px; 
+  padding: 10px 0px 0px 10px;
+  vertical-align: text-top;
+  font-family: Palatino Linotype; font-size: 15px;
+}
+
+/* Give the line numbers a nice gutter that will site between the comments and
+   the code. */
+.annotated_source_code * td.line-numbers {
+  background-color: #DDD;
+  vertical-align: text-top;
+  padding-left: 8px;
+  padding-right: 8px;
+}
+
+.annotated_source_code * td.code {
+  background-color: #F5F5FF; 
+  padding-left: 10px; 
+  padding-right: 10px;
+  width: 100%;
+  vertical-align: text-top;
+}

data/templates/default/fulldoc/html/js/docco.js

@@ -0,0 +1,14 @@
+function createAnnotatedSourceLinks() {
+    $('.method_details_list .annotated_source_code').
+        before("<span class='showSource'>[<a href='#' class='annotatedToggleSource'>View annotated source</a>]</span>");
+    $('.annotatedToggleSource').toggle(function() {
+       $(this).parent().next().slideDown(100);
+       $(this).text("Hide annotated source");
+    },
+    function() {
+        $(this).parent().next().slideUp(100);
+        $(this).text("View annotated source");
+    });
+}
+
+$(createAnnotatedSourceLinks);

data/templates/default/fulldoc/html/setup.rb

@@ -0,0 +1,7 @@
+def init
+  super
+  
+  asset("js/docco.js",file("js/docco.js",true))
+  asset("css/docco.css",file("css/docco.css",true))
+  
+end

data/templates/default/layout/html/setup.rb

@@ -0,0 +1,17 @@
+def init
+  super
+end
+
+#
+# Append yard-docco stylesheet to yard core stylesheets
+# 
+def stylesheets
+  super + %w(css/docco.css)
+end
+
+#
+# Append yard-docco javascript to yard core javascripts
+# 
+def javascripts
+  super + %w(js/docco.js)
+end

data/templates/default/method_details/html/annotated_source.erb

@@ -0,0 +1,21 @@
+<table class="annotated_source_code">
+  <tr>
+    <td colspan="3" style="padding-left: 10px;">
+      <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span></pre>
+    </td>
+  </tr>
+  <% object.annotated_source.each do |source| %>
+    <tr>
+      <td class="comment">
+        <span><%= docstring_comment Array(source.first).join("\n") %>  
+      </td>
+      <td class="line-numbers">
+        <pre class="lines" style="padding-right: 0px;"><%= h show_annotated_lines(source) %></pre>
+      </td>
+      <td class="code">
+        <pre class="code"><span class="info file"><%= html_syntax_highlight Array(source.last).join("\n") %></pre>
+      </td>
+    </tr>
+  <% end %>
+
+</table>

data/templates/default/method_details/html/setup.rb

@@ -0,0 +1,130 @@
+def init
+  super
+  
+  # Added the annotated source template to the end of the sections to be rendered.
+  sections.push(:annotated_source)
+  
+  # object contains the method details that are about to be processed. 
+  # 
+  # object.source contains all the source within the method that we can use
+  # to generate the inline documentation. We should allow for the normal sour
+  # 
+  # Source with annotations would simply look at the source and each line with 
+  # a comment would be lumped together with comments.
+  object.annotated_source = annotate_source(object.source)
+  
+end
+
+#
+# The comments within a method are just strings and have not been converted into
+# Docstrings. Here we hijack the method object and send it to the docstring
+# template to be rendered with the new docstring.
+# 
+# @param [String] comments that should be converted into a docstring and then
+#   rendered with the docstring template.
+# @return [String] the rendered results of the docstring
+def docstring_comment(comments)
+  method_object = object.dup
+  object.docstring = Docstring.new(comments,object)
+  
+  result = T('docstring').run(options)
+  object = method_object
+  result
+end
+
+#
+# This method will find the comments and then the source code (non-comments) and
+# generate an array of comment-code pairs which should be displayed next to each
+# other.
+# 
+# @param [String] source that will be scanned and annotated
+# 
+# @return [Array<Array<String,String>>] an array of arrays. Each element contains
+#   in the first element the comments, the second contains the source code.
+def annotate_source(source)
+  
+  annotated = []
+  current_comment = nil
+  current_code = nil
+  finished_comment = nil
+  
+  # Move through the source code line by line.
+  # When we come to a comment line (starts with #) then we add a source
+  # When we come to a non-comment line we are done builing that comment
+  #   we would then start to build the source up line by line
+  source.split("\n").each do |line|
+    
+    if line =~ /^\s*#.*$/
+      
+      # When parsing a comment
+      # 
+      # If we are parsing the first comment then we need to look to see if there
+      # was some code that we were parsing and finish that code. Then we need to
+      # add the comment to a new array of comments
+      # 
+      # If this is another comment, after the first one then we need to add it
+      # to the list of comments.
+      if current_comment
+        current_comment << line[/^\s*#\s?(.+)/,1].to_s
+      else
+        
+        if current_code
+          annotated << [ finished_comment, current_code ]
+          finished_comment = current_code = nil
+          
+        end
+      
+        (current_comment ||=[]) << line[/^\s*#\s?(.+)/,1].to_s
+      end
+      
+    else
+
+      # When parsing a line of code
+      # 
+      # If we are parsing the first line of code then if there are any comments
+      # then we are done with the comments that are associated with this line of
+      # code (and any lines that follow). We want to save the finished block of
+      # comments so that we can put it together with the code when we are finished
+      # with it.
+      # 
+      if current_comment
+        finished_comment = current_comment
+        current_comment = nil
+      else
+        # We were not working on a comment
+      end
+      
+      # Add the current code line to the current_code if one exists (create one if it does not exist)
+      (current_code ||= []) << line.to_s
+      
+    end
+    
+  end
+  
+  # If we have finished parsing lines and we still have code within a home, which
+  # is likely if the the source code ends with an end. We want to create a new pair
+  if current_code
+    annotated << [ finished_comment.to_s, current_code ]
+    current_code = nil
+  end
+  
+  # If we have a comment that still remains, then the comment exists without
+  # source and we should add it the pairs.
+  if current_comment
+    annotated << [ current_comment, "" ]
+    current_comment = nil
+  end
+  
+  return annotated
+end
+
+def show_annotated_lines(section)
+  @current_count ||= object.line
+  
+  # Add the comment line length to the line number
+  @current_count += Array(section.first).length
+  
+  lines = (@current_count..(@current_count+Array(section.last).length)).to_a.join("\n")
+  @current_count += Array(section.last).length
+  lines
+end

data/templates/default/method_details/html/source.erb

@@ -0,0 +1,10 @@
+<table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+    </td>
+  </tr>
+</table>

data/yard-docco.gemspec

@@ -0,0 +1,62 @@
+require 'YARD'
+require File.dirname(__FILE__) + "/lib/yard-docco"
+
+module DoccoInTheYARD
+  def self.show_version_changes(version)
+    date = ""
+    changes = []  
+    grab_changes = false
+
+    File.open("#{File.dirname(__FILE__)}/History.txt",'r') do |file|
+      while (line = file.gets) do
+
+        if line =~ /^===\s*#{version.gsub('.','\.')}\s*\/\s*(.+)\s*$/
+          grab_changes = true
+          date = $1.strip
+        elsif line =~ /^===\s*.+$/
+          grab_changes = false
+        elsif grab_changes
+          changes = changes << line
+        end
+
+      end
+    end
+
+    { :date => date, :changes => changes }
+  end
+end
+
+Gem::Specification.new do |s|
+  s.name        = 'yard-docco'
+  s.version     = ::DoccoInTheYARD::VERSION
+  s.authors     = ["Franklin Webber"]
+  s.description = %{ 
+    YARD-Docco is a YARD extension that provides an additional source view that
+    will show comments alongside the source code within a method.  }
+  s.summary     = "Docco style documentation within methods"
+  s.email       = 'franklin.webber@gmail.com'
+  s.homepage    = "http://github.com/burtlo/yard-docco"
+
+  s.platform    = Gem::Platform::RUBY
+  
+  changes = DoccoInTheYARD.show_version_changes(::DoccoInTheYARD::VERSION)
+  
+  s.post_install_message = %{
+(==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==)
+
+  Thank you for installing yard-docco #{::DoccoInTheYARD::VERSION} / #{changes[:date]}.
+  
+  Changes:
+  #{changes[:changes].collect{|change| "  #{change}"}.join("")}
+(==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==)
+
+}
+
+  s.add_dependency 'yard', '>= 0.7.0'
+  
+  s.rubygems_version   = "1.3.7"
+  s.files            = `git ls-files`.split("\n")
+  s.extra_rdoc_files = ["README.md", "History.txt"]
+  s.rdoc_options     = ["--charset=UTF-8"]
+  s.require_path     = "lib"
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: yard-docco
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Franklin Webber
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-31 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.7.0
+  type: :runtime
+  version_requirements: *id001
+description: " \n    YARD-Docco is a YARD extension that provides an additional source view that\n    will show comments alongside the source code within a method.  "
+email: franklin.webber@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+- History.txt
+files: 
+- History.txt
+- README.md
+- Rakefile
+- example/annotated_source.rb
+- lib/yard-docco.rb
+- templates/default/fulldoc/html/css/docco.css
+- templates/default/fulldoc/html/js/docco.js
+- templates/default/fulldoc/html/setup.rb
+- templates/default/layout/html/setup.rb
+- templates/default/method_details/html/annotated_source.erb
+- templates/default/method_details/html/setup.rb
+- templates/default/method_details/html/source.erb
+- yard-docco.gemspec
+has_rdoc: true
+homepage: http://github.com/burtlo/yard-docco
+licenses: []
+
+post_install_message: "\n\
+  (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==)\n\n  Thank you for installing yard-docco 1.0.0 / 2011-07-31.\n  \n  Changes:\n    \n  * Initial Release\n\
+  (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==) (==)\n\n"
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Docco style documentation within methods
+test_files: []
+