yard-appendix 0.1.5

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format doc
+--require spec_helper

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013 Instructure, Inc.
+
+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/README.md

@@ -0,0 +1,115 @@
+# yard-appendix
+
+[![Build Status](https://travis-ci.org/amireh/yard-appendix.png)](https://travis-ci.org/amireh/yard-appendix)
+
+A YARD plugin that adds support for Appendix sections like ones you find in books and papers. Appendix entries provide you with a very convenient place to write supplementary documentation, references, or advanced-usage content, that would otherwise clutter up (or even seem unrelated) a certain method or class inline-documentation.
+
+## Usage
+
+The plugin defines a `@!appendix` directive that lets you write the appendix entry with a title. You can link to in your docstrings using the explicit `@see` tag, or an inline reference as in: `(see {path to appendix})`.
+
+**Defining appendices**
+
+```ruby
+class SomeClass
+  # your methods here
+  def foo()
+  end
+
+  # @!appendix Title
+  #
+  # Appendix body goes here.
+end
+```
+
+**Referencing appendix entries**
+
+Referencing appendices is done by prefixing the appendix title with `Appendix: `. To reference the appendix defined above with the title `Title`:
+
+```ruby
+class SomeClass
+  # foo() brief
+  #
+  # Inline reference: (see {Appendix: Title})
+  #
+  # Explicit reference:
+  #
+  # @see Appendix: Title
+  def foo()
+  end
+
+  # ...
+end
+```
+
+**Note**: you can define the appendix entry wherever you want; they can be attached to a node or "free", at the bottom of the module or class definition.
+
+## Example
+
+Let's say you're writing an API controller that serves and manages Bananas in your warehouse. One of the methods is called `serve_fried_bananas()` and you want to provide some background about fried bananas that:
+
+1. is too long and would clutter up the rest of the method's documentation
+2. contains supplementary content that only users with specific uses of the method need to know about
+
+We will instead define an appendix titled `Fried Bananas`, and in our method's docstring we will reference that appendix for the user to check out.
+
+```ruby
+module FruitAPI
+
+  class BananaController
+    # Explain why one would want a fried banana, what it would do
+    # to their health and self-esteem, and any side-effects one
+    # would enjoy.
+    #
+    # @see Appendix: Fried Bananas
+    def serve_fried_bananas
+    end
+
+    # @!appendix Fried Bananas
+    #
+    # This entry will be displayed at the bottom of the class'
+    # documentation page, under a separate section aptly named
+    # 'Appendixes'.
+    #
+    # You can use tags and directives here just like you would in
+    # any other docstring.
+    #
+    # @example A fried banana in JSON
+    #   {
+    #     "id": 1,
+    #     "type": "fried",
+    #     "frying_level": "atomic"
+    #   }
+    #
+    # You can also reference other appendices: {Appendix: Fruit}
+
+    # @!appendix Fruit
+    #
+    # ...
+  end
+
+end
+```
+
+### Other stuff
+
+You can run the specs using RSpec:
+
+```bash
+cd /path/to/yard-appendix; rspec spec/
+```
+
+And you can generate the docs using YARD:
+
+```bash
+cd /path/to/yard-appendix; yardoc
+```
+
+## License
+Copyright (c) 2013 Instructure, Inc.
+
+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/lib/yard-appendix/code_objects/appendix_object.rb

@@ -0,0 +1,38 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+require 'yard/code_objects/base'
+
+module YARD
+  module CodeObjects
+
+    # An object that is spawned by the @!appendix directive.
+    #
+    # @see YARD::Tags::AppendixDirective
+    class AppendixObject < Base
+      def type; :appendix end
+      def title; "Appendix: #{name}" end
+      def path; ".#{type}.#{namespace && namespace.path}.#{name}" end
+      def to_s; "#{name}-appendix" end
+    end # AppendixObject
+  end # CodeObjects
+end # YARD

data/lib/yard-appendix/handlers/appendix_handler.rb

@@ -0,0 +1,49 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+require 'yard/handlers/ruby/comment_handler'
+
+module YARD
+  module Handlers
+    module Ruby
+      # Tracks every namespace defining statement and registers
+      # it with the NamespaceResolver.
+      #
+      # @see YARD::AppendixPlugin::NamespaceResolver
+      class AppendixHandler < CommentHandler
+        handles :class, :module
+
+        def initialize(*args)
+          super(*args)
+
+          globals.resolver ||= YARD::AppendixPlugin::NamespaceResolver.new
+        end
+
+        def process
+          globals.resolver.register_namespace(statement, namespace)
+        end
+      end # AppendixHandler
+
+      CommentHandler.inherited(AppendixHandler)
+    end # Ruby
+  end # Handlers
+end # YARD

data/lib/yard-appendix/namespace_resolver.rb

@@ -0,0 +1,149 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+module YARD
+  module AppendixPlugin
+
+    # This class is a necessary hack for locating the namespaces in which
+    # comments that are not tied to any CodeObjects were defined.
+    #
+    # The issue has been reported as a bug in Ripper and until it is solved,
+    # this is required to work around it.
+    class NamespaceResolver
+      attr_reader :namespaces
+
+      def initialize()
+        @namespaces ||= {}
+
+        super()
+      end
+
+      # Tracks the namespace the namespace-defining statement (such as class or module)
+      # was registered in. This registry is used to map between free comment statements
+      # and the namespace they're actually defined in.
+      #
+      # @param [Parser::Ruby::ClassNode, Parser::Ruby::ModuleNode] statement
+      #  the namespace defining statement
+      # @param [CodeObjects::NamespaceObject] ns the namespace object the YARD handler processor
+      #  was tracking when the statement was parsed
+      #
+      # @return [void]
+      #
+      # @see namespace_for
+      #
+      # @note
+      #  Internally called by the AppendixHandler whenever a new namespace object
+      #  is encountered.
+      def register_namespace(statement, ns)
+        klass_name = path_from_ast(statement, ns)
+
+        # already registered?
+        return if @namespaces[klass_name]
+
+        klass_path = path_from_ast(statement, ns, true)
+
+        log.debug "yard-appendix: registering path for namespace '#{klass_name}' => #{klass_path}"
+
+        @namespaces[klass_name] = klass_path
+      end
+
+      # Attempts to locate the enclosing namespace for the given
+      # statement. This is useful only for comment statements which
+      # are parsed by Ripper in a strange non-linear fashion that does not
+      # correlate with the namespace they're defined in.
+      #
+      # @param [YARD::Parser::Ruby::AstNode] statement the enclosed CommentNode
+      #  (or any other type, really)
+      # @param [YARD::CodeObjects::NamespaceObject] ns the handler's current namespace
+      # @return [CodeObjects::NamespaceObject] the enclosing namespace object
+      def namespace_for(statement, ns)
+        YARD::Registry.at(locate_enclosing_ns(statement, ns))
+      end
+
+      protected
+
+      # Attempts to locate the enclosing namespace for the given
+      # statement. This is useful only for comment statements which
+      # are parsed by Ripper in a strange non-linear fashion that does not
+      # correlate with the namespace they're defined in.
+      #
+      # @param [YARD::Parser::Ruby::AstNode] statement the enclosed CommentNode
+      #  (or any other type, really)
+      # @param [YARD::CodeObjects::NamespaceObject] ns the handler's current namespace
+      # @return [String] a Registry path to the enclosing namespace object
+      #
+      # @note
+      #  You shouldn't need to use this directly. Use #namespace_for instead.
+      #
+      # @see #namespace_for
+      def locate_enclosing_ns(statement, ns)
+
+        unless ns || CodeObjects::NamespaceObject === ns || String === ns
+          raise ArgumentError.new "A valid NamespaceObject must be passed."
+        end
+
+        if ns.is_a?(String)
+          ns = YARD::Registry.at(ns)
+        end
+
+        lines_to_namespaces = {}
+        statement.parent.traverse { |ast|
+          next unless [:module, :class].include?(ast.type)
+
+          if ast.line_range.include?(statement.line)
+            lines_to_namespaces[ast.line] = ast
+          end
+        }
+
+        closest = {}
+        lines_to_namespaces.each_pair { |line, ast|
+          distance = statement.line - line
+          if closest.empty? || distance < closest[:distance]
+            closest = { node: ast, distance: distance }
+          end
+        }
+
+        path_to(closest[:node], ns)
+      end
+
+      def path_from_ast(node, ns, fully_qualified = false)
+        path = ''
+
+        if fully_qualified
+          unless ns.to_s.empty? || ns.to_s == 'root'
+            path = ns.to_s + '::'
+          end
+        end
+
+        path += case node.type
+        when :class;  node.class_name.path.first
+        when :module; node.module_name.path.first
+        end
+      end
+
+      def path_to(ast, ns)
+        (ast && @namespaces[path_from_ast(ast, ns)]) || ns.to_s
+      end
+
+    end
+  end
+end

data/lib/yard-appendix/tags/appendix_directive.rb

@@ -0,0 +1,92 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+require 'yard/tags/directives'
+
+module YARD
+  module Tags
+
+    # Defines a @!appendix directive that allows writing Appendix
+    # entries which will be attached to the end of the namespace's
+    # output, similar to appendixes in books or documents.
+    #
+    # @example Appendix definition syntax
+    #  module SomeModule
+    #    # @!appendix Title
+    #    #
+    #    # Appendix body.
+    #  end
+    #
+    # @note When defining an appendix entry, there's no need to
+    #  prefix its name with 'Appendix: ' as that is automatically
+    #  done for you.
+    #
+    # @example Defining an appendix titled 'API Response Codes'
+    #
+    #  class BananaAPIController
+    #    # Explain why one would want a fried banana, what it would do
+    #    # to their health and self-esteem, and any side-effects one
+    #    # would enjoy.
+    #    #
+    #    # @see Appendix: API Response Codes
+    #    def serve_fried_bananas
+    #    end
+    #
+    #    # @!appendix API Response Codes
+    #    #
+    #    # The following map explains the HTTP response codes returned
+    #    # by our servers and how you should treat them:
+    #    #
+    #    #   1. 200 -> a banana is available
+    #    #   1. 403 -> that banana is super exclusive
+    #    #   1. 404 -> no such banana, verify the ID
+    #  end
+    #
+    # You can also reference the appendix identified by `Title` in
+    # other parts of your namespace documentation strings by using
+    # the @see tag. See the "See Also" link for more info about
+    # referencing appendices.
+    #
+    # @see YARD::AppendixPlugin::AppendixLinker
+    class AppendixDirective < Directive
+
+      def statement;    handler.statement; end
+      def namespace;    handler.namespace; end
+      def resolver;     handler.globals.resolver; end
+
+      def call
+        # no resolver? then use the handler's namespace
+        comment_ns = handler.namespace
+
+        if resolver
+          comment_ns = resolver.namespace_for(statement, namespace)
+          log.debug "yard-appendix: appendix #{tag.name} will be enclosed under #{comment_ns}"
+        end
+
+        log.info "yard-appendix: appendix #{tag.name} has been registered under #{comment_ns.name}"
+        appendix = CodeObjects::AppendixObject.new(comment_ns, tag.name)
+        handler.register_docstring appendix, tag.text
+        handler.register_file_info appendix
+      end
+    end
+  end
+end

data/lib/yard-appendix/templates/helpers/html_helper.rb

@@ -0,0 +1,120 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+require 'yard/templates/helpers/html_helper'
+
+module YARD
+  module AppendixPlugin
+    module AppendixLinker
+
+      # Handles reference links to Appendix objects in @see tags
+      # by printing out their readable titles in the anchor text and tooltip.
+      #
+      # Delegates to YARD::Templates::Helpers::HtmlHelper#linkify if
+      # the @see tag syntax does not qualify as an appendix one.
+      #
+      # @example Referencing appendix objects:
+      #
+      #  # Some method description.
+      #  # ...
+      #  # @see Appendix: Bananas
+      #  def some_method()
+      #  end
+      #
+      # Note that the syntax expected is `@see Appendix: APPENDIX_NAME` where
+      # only the `APPENDIX_NAME` is variable.
+      #
+      # @note
+      #  Appendix links will be resolved only within the namespace they're defined in (class or module).
+      #
+      def linkify(link, *args)
+        if link == 'Appendix:' && !args.empty?
+          if res = link_appendix(args.first)
+            return res
+          end
+        end
+
+        super(link, *args)
+      end
+
+      def link_appendix(in_title)
+        appendix, title = nil, in_title.to_s.strip.to_sym
+        ns = nil # used for reporting in case we couldn't locate it
+
+        if object
+          # try in the object scope
+          ns = object
+          appendix = YARD::Registry.at(".appendix.#{object.path}.#{title}")
+
+          # try in the object's namespace scope
+          if appendix.nil? && object.respond_to?(:namespace)
+            ns = object.namespace
+            appendix = YARD::Registry.at(".appendix.#{object.namespace.path}.#{title}")
+          end
+        # else
+          # this shouldn't happen (use stub!(:object) in specs)
+          # appendix = YARD::Registry.all(:appendix).select { |a| a.name == title }.first
+        end
+
+        unless appendix.nil?
+          link = url_for(appendix, nil, true)
+          link = link ? link_url(link, appendix.title, :title => h(appendix.title)) : appendix.title
+
+          return "<span class='object_link'>#{link}</span>"
+        end
+
+        log.warn %Q[unable to locate referenced appendix '#{title}'#{ns ? " in namespace " + ns.name.to_s : ''}]
+        nil
+      end
+    end
+  end
+end
+
+module YARD
+  module Templates
+    module Helpers
+      module HtmlHelper
+        include YARD::AppendixPlugin::AppendixLinker
+      end
+    end
+  end
+end
+
+# module YARD::Templates::Helpers::HtmlHelper
+#   alias_method :old_link_object, :link_object # yeah...
+#
+#   def link_object(obj, otitle = nil, anchor = nil, relative = true)
+#     if obj && obj.is_a?(String) && obj == 'Appendix:'
+#       appendix = object.namespace.children.select { |o| o.type == :appendix && o.title == "Appendix: #{otitle}" }.first
+#
+#       unless appendix.nil?
+#         link = url_for(appendix, anchor, relative)
+#         link = link ? link_url(link, appendix.title, :title => h(appendix.title)) : appendix.title
+#
+#         return "<span class='object_link'>#{link}</span>"
+#       end
+#     end
+#
+#     return old_link_object(obj, otitle, anchor, relative)
+#   end
+#
+# end

data/lib/yard-appendix/version.rb

@@ -0,0 +1,27 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+module YARD
+  module AppendixPlugin
+    VERSION = "0.1.5"
+  end
+end

data/lib/yard-appendix.rb

@@ -0,0 +1,46 @@
+#
+# Copyright (c) 2011 Ahmad Amireh <ahmad@amireh.net>
+#
+# 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.
+#
+
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
+
+require 'yard'
+require 'yard-appendix/version'
+require 'yard-appendix/namespace_resolver'
+require 'yard-appendix/code_objects/appendix_object'
+require 'yard-appendix/tags/appendix_directive'
+require 'yard-appendix/handlers/appendix_handler'
+require 'yard-appendix/templates/helpers/html_helper'
+
+module YARD
+  module AppendixPlugin
+    ROOT          = File.dirname(__FILE__)
+    TEMPLATE_PATH = File.join(%W[#{ROOT} .. templates])
+  end
+
+  module Templates
+    Engine.register_template_path YARD::AppendixPlugin::TEMPLATE_PATH
+  end
+
+  module Tags
+    Library.define_directive(:appendix, :with_title_and_text, AppendixDirective)
+  end
+end

data/spec/code_objects/appendix_object_spec.rb

@@ -0,0 +1,66 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+include CodeObjects
+
+describe YARD::CodeObjects::AppendixObject do
+  before { Registry.clear }
+
+  it "should create an appendix object" do
+    o1 = AppendixObject.new(:root, 'Zoo')
+  end
+
+  it "should respect uniqueness of appendix titles in scope" do
+    # root scope, same titles:
+    o1 = AppendixObject.new(:root, 'Zoo')
+    o2 = AppendixObject.new(:root, 'Zoo')
+    o1.should == o2
+
+    # root scope, different titles:
+    o3 = AppendixObject.new(:root, 'Monkeys')
+    o4 = AppendixObject.new(:root, 'Parrots')
+    o3.should_not == o4
+
+    # custom scope:
+    YARD.parse_string <<-'eof'
+      module TheZoo
+        module ParrotZone
+        end
+      end
+    eof
+
+    # same scope, same title:
+    o1 = AppendixObject.new(Registry.at('TheZoo'), 'Animals')
+    o2 = AppendixObject.new(Registry.at('TheZoo'), 'Animals')
+    o1.should == o2
+
+    # same scope, different title:
+    o1 = AppendixObject.new(Registry.at('TheZoo'), 'Monkeys')
+    o2 = AppendixObject.new(Registry.at('TheZoo'), 'Parrots')
+    o1.should_not == o2
+
+    # same title, different scope:
+    o3 = AppendixObject.new(Registry.at('TheZoo.ParrotZone'), 'Monkeys')
+    o1.should_not == o3
+  end
+
+end

data/spec/handlers/appendix_handler_spec.rb

@@ -0,0 +1,117 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+include Handlers::Ruby
+
+describe YARD::Handlers::Ruby::AppendixHandler do
+
+  before {
+    Registry.clear
+
+    class StubHandler < AppendixHandler
+      handles :class, :module
+
+      def self.resolver; @@resolver end
+      def process; @@resolver ||= globals.resolver end
+
+      # have to do this manually as to not clutter up the other specs
+      AppendixHandler.clear_subclasses
+    end
+
+    AppendixHandler.inherited(StubHandler)
+  }
+
+  after {
+    AppendixHandler.clear_subclasses
+  }
+
+  it "should track a namespace statement" do
+    YARD.parse_string <<-'eof'
+      module SomeModule
+        class SomeClass
+          # comment in SomeClass
+        end
+
+        # comment in SomeModule
+      end
+    eof
+
+    StubHandler.resolver.namespaces.size.should == 2
+    StubHandler.resolver.namespaces["SomeModule"].should == "SomeModule"
+    StubHandler.resolver.namespaces["SomeClass"].should == "SomeModule::SomeClass"
+  end
+
+  it "should locate an enclosing ns for a comment" do
+    class StubCommentHandler < Handlers::Ruby::Base
+      handles :comment
+
+      class << self
+        def comments; @@comments end
+      end
+
+      def process
+        @@comments ||= []
+        @@comments << [ statement, namespace ] if statement.type == :comment
+      end
+    end
+
+
+    YARD.parse_string <<-'eof'
+      module SomeModule
+        class SomeClass
+          def f() end
+          # comment in SomeClass
+        end
+
+        # comment in SomeModule
+      end
+
+      # comment in :root
+    eof
+
+    comments = StubCommentHandler.comments
+    comments.size.should == 3
+
+    resolver = StubHandler.resolver
+    resolver.namespaces.size.should == 2
+
+    resolver.
+      namespace_for(
+        comments[0][0],
+        comments[0][1]).
+      should == Registry.at('SomeModule::SomeClass')
+
+    resolver.
+      namespace_for(
+        comments[1][0],
+        comments[1][1]).
+      should == Registry.at('SomeModule')
+
+    resolver.
+      namespace_for(
+        comments[2][0],
+        comments[2][1]).
+      should == Registry.at(:root)
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,44 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+require 'yard'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard-appendix')
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+
+  include YARD
+end

data/spec/tags/appendix_directive_spec.rb

@@ -0,0 +1,137 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+include YARD::Tags
+
+describe YARD::Tags::AppendixDirective do
+  before { Registry.clear }
+
+  it "should build an AppendixObject" do
+    YARD.parse_string <<-'eof'
+      module TheQuestion
+        module TheAnswer
+          # @!appendix 42
+        end
+
+        # @!appendix Life, the Universe, and Everything
+      end
+    eof
+
+    appendixes = Registry.all(:appendix)
+    appendixes.count.should == 2
+    appendixes[0].namespace.should == Registry.at("TheQuestion::TheAnswer")
+    appendixes[1].namespace.should == Registry.at("TheQuestion")
+
+  end
+
+  it "should allow for more than one AppendixObject" do
+    YARD.parse_string <<-'eof'
+      module TheQuestion
+        module TheAnswer
+          # @!appendix 42
+        end
+
+        # @!appendix Life, the Universe, and Everything
+        #
+        # But what is it?
+
+        # @!appendix DeepThought
+        #
+        # YEEHAA
+      end
+    eof
+
+    appendixes = Registry.all(:appendix)
+    appendixes.count.should == 3
+    appendixes[0].namespace.should == Registry.at("TheQuestion::TheAnswer")
+    appendixes[1].namespace.should == Registry.at("TheQuestion")
+    appendixes[2].namespace.should == Registry.at("TheQuestion")
+
+  end
+
+  it "should implicitly prefix an appendix's title with Appendix: " do
+    YARD.parse_string <<-'eof'
+      module TheQuestion
+        # @!appendix Life, the Universe, and Everything
+        #
+        # But what is it?
+      end
+    eof
+
+    appendixes = Registry.all(:appendix)
+    appendixes.count.should == 1
+    appendixes[0].title.should == 'Appendix: Life, the Universe, and Everything'
+
+  end
+
+  it "should build an appendix in the root namespace" do
+    YARD.parse_string <<-'eof'
+      # @!appendix Life, the Universe, and Everything
+      #
+      # But what is it?
+    eof
+
+    appendixes = Registry.all(:appendix)
+    appendixes.count.should == 1
+    appendixes[0].namespace.should == Registry.root
+  end
+
+  it "should manage oddly titled appendices" do
+
+    [ 'Appendix: Life, the Universe, and Everything',
+      '#__ Booyah',
+      '123456789',
+      '\n',
+      '<lol>'
+    ].each do |some_title|
+      YARD.parse_string %Q[
+        module TheQuestion
+          # @!appendix #{some_title}
+          #
+          # Some body.
+        end
+      ]
+
+      appendixes = Registry.all(:appendix)
+      appendixes.count.should == 1
+      appendixes[0].title.should == 'Appendix: %s' %[some_title]
+
+      Registry.clear
+    end
+  end
+
+  it "should ignore an appendix with no title" do
+    log.should_receive(:warn).with(/Invalid directive format for @!appendix/)
+
+    YARD.parse_string <<-'eof'
+      module TheQuestion
+        # @!appendix
+        #
+        # But what is it?
+      end
+    eof
+
+
+    Registry.all(:appendix).count.should == 0
+  end
+
+end

data/spec/templates/helpers/html_helper_spec.rb

@@ -0,0 +1,70 @@
+#
+# Copyright (c) 2013 Instructure, Inc.
+#
+# 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.
+#
+
+describe YARD::AppendixPlugin::AppendixLinker do
+  include YARD::Templates::Helpers::BaseHelper
+  include YARD::Templates::Helpers::HtmlHelper
+  include YARD::Templates::Helpers::MethodHelper
+
+  before {
+    Registry.clear
+  }
+
+  it "should linkify an appendix object" do
+    linkify('Appendix: Booyah').should == 'Appendix: Booyah'
+
+
+    YARD.parse_string <<-'eof'
+      module TheAnswer
+        # @!appendix 42
+        #
+        # Vroom vroom.
+      end
+    eof
+
+    Registry.all(:appendix).count.should == 1
+
+    stub!(:serializer).and_return(Serializers::FileSystemSerializer.new)
+    stub!(:object).and_return(Registry.all(:appendix).first)
+
+    linkify('Appendix:','42').should match(%r{<a href="#42-appendix".*>Appendix: 42</a>})
+  end
+
+  it "should linkify an appendix with any title" do
+    YARD.parse_string <<-'eof'
+      module TheAnswer
+        # @!appendix Life, the Universe, and Everything
+        #
+        # Vroom vroom.
+      end
+    eof
+
+    Registry.all(:appendix).count.should == 1
+
+    stub!(:serializer).and_return(Serializers::FileSystemSerializer.new)
+    stub!(:object).and_return(Registry.all(:appendix).first)
+
+    linkify('Appendix:','Life, the Universe, and Everything').should match(
+      %r{<a href="#Life%2C\+the\+Universe%2C\+and\+Everything\-appendix".*>Appendix: Life, the Universe, and Everything</a>})
+  end
+
+end

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

@@ -0,0 +1,26 @@
+def init
+  super
+  sections :appendix, [ :appendix_entry, [ T('docstring')] ]
+end
+
+def appendix
+  unless @appendixes
+    return if !object.respond_to?(:type) || !object.is_a?(YARD::CodeObjects::Base) || object.type == :appendix
+  end
+
+  @appendixes ||= object.children.select { |o| o.type == :appendix }
+  
+  return if @appendixes.empty?
+  
+  log.info "yard-appendix: found #{@appendixes.count} appendix entries for #{object}"
+  
+  erb :listing
+end
+
+def appendix_entry
+  return unless object.type == :appendix
+  
+  log.info "yard-appendix: rendering appending entry #{object.title}"
+  
+  erb :entry
+end

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

@@ -0,0 +1,4 @@
+def init
+  super
+  sections.push T('appendix')
+end

data/yard-appendix.gemspec

@@ -0,0 +1,25 @@
+require File.join(%W[#{File.dirname(__FILE__)} lib yard-appendix version])
+
+Gem::Specification.new do |s|
+  s.name        = 'yard-appendix'
+  s.summary     = "A YARD plugin that adds support for Appendix sections."
+  s.description = <<-eof
+    yard-appendix is a plugin for YARD, the Ruby documentation generation tool,
+    that defines a special directive @!appendix for writing appendixes for your
+    code documentation, similar to appendixes you find in books.
+
+    Appendix entries can be referenced to by methods and classes in your docs
+    using the @see tag and inline-references, just like any other object.
+  eof
+  s.version     = YARD::AppendixPlugin::VERSION
+  s.date        = Time.now.strftime('%Y-%m-%d')
+  s.authors     = ["Ahmad Amireh"]
+  s.email       = 'ahmad@instructure.com'
+  s.homepage    = 'https://github.com/amireh/yard-appendix'
+  s.files       = Dir.glob("{lib,spec,templates}/**/*.rb") +
+                  ['LICENSE', 'README.md', '.rspec', __FILE__]
+  s.has_rdoc    = 'yard'
+  s.license     = 'MIT'
+  s.add_dependency('yard', '>= 0.8.0')
+  s.add_development_dependency 'rspec'
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: yard-appendix
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+  prerelease: 
+platform: ruby
+authors:
+- Ahmad Amireh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! "    yard-appendix is a plugin for YARD, the Ruby documentation generation
+  tool,\n    that defines a special directive @!appendix for writing appendixes for
+  your\n    code documentation, similar to appendixes you find in books.\n\n    Appendix
+  entries can be referenced to by methods and classes in your docs\n    using the
+  @see tag and inline-references, just like any other object.\n"
+email: ahmad@instructure.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/yard-appendix/code_objects/appendix_object.rb
+- lib/yard-appendix/version.rb
+- lib/yard-appendix/handlers/appendix_handler.rb
+- lib/yard-appendix/namespace_resolver.rb
+- lib/yard-appendix/tags/appendix_directive.rb
+- lib/yard-appendix/templates/helpers/html_helper.rb
+- lib/yard-appendix.rb
+- spec/code_objects/appendix_object_spec.rb
+- spec/handlers/appendix_handler_spec.rb
+- spec/spec_helper.rb
+- spec/tags/appendix_directive_spec.rb
+- spec/templates/helpers/html_helper_spec.rb
+- templates/default/appendix/html/setup.rb
+- templates/default/module/html/setup.rb
+- LICENSE
+- README.md
+- .rspec
+- yard-appendix.gemspec
+homepage: https://github.com/amireh/yard-appendix
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+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.8.23
+signing_key: 
+specification_version: 3
+summary: A YARD plugin that adds support for Appendix sections.
+test_files: []
+has_rdoc: yard