yard-api 0.1.1

data/README.md

@@ -0,0 +1,27 @@
+# yard-api
+
+[![Build Status](https://travis-ci.org/amireh/yard-api.png)](https://travis-ci.org/amireh/yard-api)
+
+TODO
+
+## Usage
+
+TODO
+
+## Notes
+
+- can only document classes and class methods; modules, root objects, and constants are ignored
+
+## Changelog
+
+**10/9/2014**
+
+- Support for github-flavored markdown when you're using Markdown as a markup, and `redcarpet` as the provider
+- Syntax highlighting for multiple languages (with auto-detection) using [highlight.js](https://highlightjs.org/)
+- `@example_response` and `@example_request` tags now support a title for the response
+- A new option: `copyright` for displaying a copyright in the footer of every page
+- A new option: `footer_note` for displaying a custom note, like linking to the project's source code, in the footer of every page
+
+## License
+
+Released under the [AGPLv3](http://www.gnu.org/licenses/agpl-3.0.html) license.

data/lib/yard-api/markup/redcarpet.rb

@@ -0,0 +1,42 @@
+require 'redcarpet'
+require 'yard/templates/helpers/markup_helper'
+
+module YARD::APIPlugin::Markup
+  # TODO: make this configurable
+  class RedcarpetDelegate
+    Extensions = {
+      no_intra_emphasis: true,
+      fenced_code_blocks: true,
+      autolink: true,
+      tables: true,
+      lax_spacing: false,
+      space_after_headers: true,
+      underline: true,
+      highlight: true,
+      footnotes: true
+    }.freeze
+
+    RendererOptions = {
+    }.freeze
+
+    def initialize(text, extensions_and_options=nil)
+      @renderer = Redcarpet::Render::HTML.new(RendererOptions)
+      @markdown = Redcarpet::Markdown.new(@renderer, Extensions)
+      @text = text
+    end
+
+    def to_html
+      @markdown.render(@text)
+    end
+  end
+end
+
+module YARD::Templates::Helpers
+  if MarkupHelper.markup_cache.nil?
+    MarkupHelper.clear_markup_cache
+  end
+
+  MarkupHelper.markup_cache[:markdown] ||= {}
+  MarkupHelper.markup_cache[:markdown][:class] = YARD::APIPlugin::Markup::RedcarpetDelegate
+end
+

data/lib/yard-api/options.rb

@@ -0,0 +1,13 @@
+module YARD::APIPlugin
+  class Options < YARD::Options
+    default_attr :title, 'Rails API Project'
+    default_attr :static, []
+    default_attr :files, []
+    default_attr :route_namespace, ''
+
+    default_attr :footer_copyright, nil
+    default_attr :footer_note, nil
+
+    attr_accessor :readme
+  end
+end

data/lib/yard-api/railtie.rb

@@ -0,0 +1,11 @@
+require 'rails'
+
+module YARD::APIPlugin
+  class Railtie < ::Rails::Railtie
+    railtie_name :yard_api
+
+    rake_tasks do
+      load File.join(YARD::APIPlugin::TASK_PATH, 'yard_api.rake')
+    end
+  end
+end

data/lib/yard-api/tags.rb

@@ -0,0 +1,16 @@
+YARD::Tags::Library.define_tag("API endpiont", :API)
+YARD::Tags::Library.define_tag("API endpiont argument", :argument)
+YARD::Tags::Library.define_tag("API response field", :request_field)
+YARD::Tags::Library.define_tag("API response field", :response_field)
+YARD::Tags::Library.define_tag("API example request", :example_request, :with_title_and_text)
+YARD::Tags::Library.define_tag("API example response", :example_response, :with_title_and_text)
+YARD::Tags::Library.define_tag("API subtopic", :subtopic)
+YARD::Tags::Library.define_tag("API Object Definition", :object)
+YARD::Tags::Library.define_tag("API Return Type", :returns)
+YARD::Tags::Library.define_tag("API resource is beta", :beta)
+YARD::Tags::Library.define_tag("API resource is internal", :internal)
+YARD::Tags::Library.define_tag("API empty response", :no_content)
+YARD::Tags::Library.define_tag("API error", :throws)
+YARD::Tags::Library.define_tag("API warning", :warning)
+YARD::Tags::Library.define_tag("API note", :note)
+YARD::Tags::Library.define_tag("API message", :emits)

data/lib/yard-api/templates/helpers/base_helper.rb

@@ -0,0 +1,108 @@
+require 'yard/templates/helpers/base_helper'
+
+module YARD::Templates::Helpers::BaseHelper
+  def api_options()
+    YARD::APIPlugin.options
+  end
+
+  def linkify_with_api(*args)
+    # References to controller actions
+    #
+    # Syntax: api:ControllerName#method_name [TITLE OVERRIDE]
+    #
+    # @example Explicit reference with title defaulting to the action
+    #  # @see api:Assignments#create
+    #  # => <a href="assignments.html#method.assignments_api.create">create</a>
+    #
+    # @example Inline reference with an overriden title
+    #   # Here's a link to absolute {api:Assignments#destroy destruction}
+    #   # => <a href="assignments.html#method.assignments_api.destroy">destruction</a>
+    #
+    # @note Action links inside the All Resources section will be relative.
+    if args.first.is_a?(String) && args.first =~ %r{^api:([^#]+)#(.*)}
+      topic, controller = *lookup_topic($1.to_s)
+      if topic
+        html_file = "#{topicize topic.first}.html"
+        action = $2
+        link_url("#{html_file}#method.#{topicize(controller.name.to_s).sub("_controller", "")}.#{action}", args[1])
+      else
+        raise "couldn't find API link for #{args.first}"
+      end
+
+    # References to API objects defined by @object
+    #
+    # Syntax: api:ControllerName:Object+Name [TITLE OVERRIDE]
+    #
+    # @example Explicit resource reference with title defaulting to its name
+    #   # @see api:Assignments:Assignment
+    #   # => <a href="assignments.html#Assignment">Assignment</a>
+    #
+    # @example Explicit resource reference with an overriden title
+    #   # @return api:Assignments:AssignmentOverride An Assignment Override
+    #   # => <a href="assignments.html#Assignment">An Assignment Override</a>
+    elsif args.first.is_a?(String) && args.first =~ %r{^api:([^:]+):(.*)}
+      scope_name, resource_name = $1.downcase, $2.gsub('+', ' ')
+      link_url("#{scope_name}.html##{resource_name}", args[1] || resource_name)
+    elsif args.first.is_a?(String) && args.first == 'Appendix:' && args.size > 1
+      __errmsg = "unable to locate referenced appendix '#{args[1]}'"
+
+      unless appendix = lookup_appendix(args[1].to_s)
+        raise __errmsg
+      end
+
+      topic, controller = *lookup_topic(appendix.namespace.to_s)
+
+      if topic
+        html_file = "#{topicize topic.first}.html"
+        bookmark = "#{appendix.name.to_s.gsub(' ', '+')}-appendix"
+        ret = link_url("#{html_file}##{bookmark}", appendix.title)
+      else
+        raise __errmsg
+      end
+
+    # A non-API link, delegate to YARD's HTML linker
+    else
+      linkify_without_api(*args)
+    end
+  end
+
+  alias_method :linkify_without_api, :linkify
+  alias_method :linkify, :linkify_with_api
+
+  def lookup_topic(controller_name)
+    controller = nil
+    topic = options[:resources].find { |r,cs|
+      cs.any? { |c|
+        controller = c if c.name.to_s == controller_name
+        !controller.nil?
+      }
+    }
+
+    [ topic, controller ]
+  end
+
+  def lookup_appendix(title)
+    appendix = nil
+
+    puts "looking up appendix: #{title}"
+
+    if object
+      # try in the object scope
+      appendix = YARD::Registry.at(".appendix.#{object.path}.#{title}")
+
+      # try in the object's namespace scope
+      if appendix.nil? && object.respond_to?(:namespace)
+        appendix = YARD::Registry.at(".appendix.#{object.namespace.path}.#{title}")
+      end
+    end
+
+    appendix
+  end
+
+  def tag_partial(name, tag)
+    options[:tag] = tag
+    out = erb(name)
+    options.delete(:tag)
+    out
+  end
+end

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

@@ -0,0 +1,87 @@
+require 'yard/templates/helpers/html_helper'
+
+module YARD::Templates::Helpers::HtmlHelper
+  def topicize(str)
+    str.gsub(' ', '_').underscore
+  end
+
+  def url_for_file(filename, anchor = nil)
+    link = filename.filename
+    link += (anchor ? '#' + urlencode(anchor) : '')
+    link
+  end
+
+  def static_pages()
+    options = YARD::APIPlugin.options
+
+    paths = Array(options.static).map do |entry|
+      pages = if entry.is_a?(Hash)
+        glob = entry['glob']
+        blacklist = Array(entry['exclude'])
+
+        unless glob
+          raise "Invalid static page entry, expected Hash to contain a 'glob' parameter: #{entry}"
+        end
+
+        pages = Dir.glob(entry['glob'])
+
+        if blacklist.any?
+          pages.delete_if { |p| blacklist.any? { |filter| p.match(filter) } }
+        end
+
+        pages
+      elsif entry.is_a?(Array)
+        entry.map(&:to_s)
+      elsif entry.is_a?(String)
+        [ entry ]
+      end
+    end.flatten.compact
+
+    markdown_exts = YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS[:markdown]
+    readme_page = options.readme
+    pages = Dir.glob(paths)
+
+    if readme_page.present?
+      pages.delete_if { |page| page.match(readme_page) }
+    end
+
+    pages.map do |page|
+      filename = 'file.' + File.split(page).last.sub(/\..*$/, '.html')
+
+      # extract page title if it's a markdown document; title is expected to
+      # be an h1 on the very first line:
+      title = if markdown_exts.include?(File.extname(page).sub('.', ''))
+        (File.open(page, &:gets) || '').strip.sub('# ', '')
+      else
+        # otherwise we'll just sanitize the file name
+        File.basename(page).sub(/\.\w+$/, '').gsub(/\W/, ' ').gsub(/\s+/, ' ').capitalize
+      end
+
+      {
+        src: page,
+        filename: filename,
+        title: title
+      }
+    end
+  end
+
+  # override yard-appendix link_appendix
+  def link_appendix(ref)
+    __errmsg = "unable to locate referenced appendix '#{ref}'"
+
+    puts "looking up appendix: #{ref}"
+    unless appendix = lookup_appendix(ref.to_s)
+      raise __errmsg
+    end
+
+    topic, controller = *lookup_topic(appendix.namespace.to_s)
+
+    unless topic
+      raise __errmsg
+    end
+
+    html_file = "#{topicize topic.first}.html"
+    bookmark = "#{appendix.name.to_s.gsub(' ', '+')}-appendix"
+    link_url("#{html_file}##{bookmark}", appendix.title)
+  end
+end

data/lib/yard-api/templates/helpers/route_helper.rb

@@ -0,0 +1,19 @@
+module YARD::Templates::Helpers
+  module RouteHelper
+    def self.routes_for(prefix)
+      Rails.application.routes.set
+    end
+
+    def self.matches_controller_and_action?(route, controller, action)
+      route.requirements[:controller] == controller &&
+      route.requirements[:action] == action
+    end
+
+    def self.api_methods_for_controller_and_action(controller, action)
+      @routes ||= self.routes_for('/')
+      controller_path = [ YARD::APIPlugin.options.route_namespace, controller ].join('/')
+      controller_path.gsub!(/^\/|_controller$/, '')
+      @routes.find_all { |r| matches_controller_and_action?(r, controller_path, action) }
+    end
+  end
+end

data/lib/yard-api/verifier.rb

@@ -0,0 +1,34 @@
+module YARD
+  module APIPlugin
+    class Verifier < ::YARD::Verifier
+      def initialize(verbose=false)
+        @verbose = verbose
+        super()
+      end
+
+      def run(list)
+        relevant = list.select { |o| relevant_object?(o) }
+
+        if @verbose && relevant.any?
+          puts "#{relevant.length}/#{list.length} objects are relevant:"
+          relevant.each do |object|
+            puts "\t- #{object.path}"
+          end
+        end
+
+        relevant
+      end
+
+      def relevant_object?(object)
+        case object.type
+        when :root, :module, :constant
+          false
+        when :method, :class
+          !object.tags('API').empty? && object.tags('internal').empty?
+        else
+          object.parent.nil? && relevant_object?(object.parent)
+        end
+      end
+    end
+  end
+end

data/lib/yard-api/version.rb

@@ -0,0 +1,5 @@
+module YARD
+  module APIPlugin
+    VERSION = "0.1.1"
+  end
+end

data/lib/yard-api/yardoc_task.rb

@@ -0,0 +1,78 @@
+require 'fileutils'
+
+module YARD::APIPlugin
+  class YardocTask < ::YARD::Rake::YardocTask
+    attr_reader :config
+
+    def initialize()
+      super(:yard_api, &:run)
+    end
+
+    def run
+      @config = load_config
+      t = self
+
+      YARD::APIPlugin.options.update(@config)
+
+      t.verifier = YARD::APIPlugin::Verifier.new(config['verbose'])
+      t.before = proc { FileUtils.rm_rf(config['output']) }
+      t.files = config['files']
+
+      config['debug'] ||= ENV['DEBUG']
+      config['verbose'] ||= ENV['VERBOSE']
+
+      set_option('template', 'api')
+      set_option('no-yardopts')
+      set_option('no-document')
+
+      set_option('markup', config['markup']) if config['markup']
+      set_option('markup-provider', config['markup_provider']) if config['markup_provider']
+
+      if config['markup_provider'] == 'redcarpet'
+        require 'yard-api/markup/redcarpet'
+      end
+
+      set_option('title', config['title'])
+      set_option('output-dir', config['output'])
+      set_option('readme', config['readme']) if File.exists?(config['readme'])
+      set_option('verbose') if config['verbose']
+      set_option('debug') if config['debug']
+
+      get_assets(config).each_pair do |asset_id, rpath|
+        asset_path = File.join(config['source'], rpath)
+
+        if File.directory?(asset_path)
+          set_option 'asset', [ asset_path, asset_id ].join(':')
+        elsif config['strict']
+          raise <<-Error
+            Expected assets of type "#{asset_id}" to be found within
+            "#{asset_path}", but they are not.
+          Error
+        end
+      end
+
+      if config['debug']
+        puts "Invoking YARD with options: #{self.options.to_json}"
+      end
+    end
+
+    private
+
+    def load_config
+      path = Rails.root.join('config', 'yard_api.yml')
+
+      # load defaults
+      config = YAML.load_file(File.join(YARD::APIPlugin::CONFIG_PATH, 'yard_api.yml'))
+      config.merge!(YAML.load_file(path)) if File.exists?(path)
+      config
+    end
+
+    def set_option(k, *vals)
+      self.options.concat(["--#{k}", *vals])
+    end
+
+    def get_assets(config)
+      config['assets'] || {}
+    end
+  end
+end

data/lib/yard-api.rb

@@ -0,0 +1,48 @@
+# yard-api - a YARD plugin for generating API documentation in Rails.
+#
+# Copyright (C) 2014 Ahmad Amireh <ahmad@instructure.com>
+# Copyright (C) 2011 Instructure, Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
+
+require 'yard'
+require 'yard-appendix'
+
+module YARD
+  module APIPlugin
+    ROOT          = File.dirname(__FILE__)
+    CONFIG_PATH   = File.join(%W[#{ROOT} .. config])
+    TEMPLATE_PATH = File.join(%W[#{ROOT} .. templates])
+    TASK_PATH     = File.join(%W[#{ROOT} .. tasks])
+
+    def self.options
+      @@options ||= Options.new
+    end
+  end
+
+  require 'yard-api/version'
+  require 'yard-api/options'
+  require 'yard-api/tags'
+  require 'yard-api/verifier'
+  require 'yard-api/templates/helpers/base_helper'
+  require 'yard-api/templates/helpers/html_helper'
+  require 'yard-api/templates/helpers/route_helper'
+  require 'yard-api/railtie' if defined?(Rails)
+
+  module Templates
+    Engine.register_template_path YARD::APIPlugin::TEMPLATE_PATH
+  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-api')
+
+# 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/tasks/yard_api.rake

@@ -0,0 +1,13 @@
+require 'fileutils'
+require 'yard-api/yardoc_task'
+
+runner = YARD::APIPlugin::YardocTask.new
+
+desc 'generate YARD API docs'
+task :yard_api => :environment do |t|
+  output = runner.config['output']
+  puts <<-Message
+    API Documentation successfully generated in #{output}
+    See #{output}/index.html
+  Message
+end

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

@@ -0,0 +1,19 @@
+include T('default/appendix/html')
+
+def init
+  super
+end
+
+def appendix
+  controllers = options[:controllers]
+
+  unless controllers && controllers.is_a?(Array)
+    return
+  end
+
+  @appendixes = controllers.collect { |c|
+    c.children.select { |o| :appendix == o.type }
+  }.flatten
+
+  super
+end

data/templates/api/docstring/html/setup.rb

@@ -0,0 +1,3 @@
+def init
+  sections :text, T('tags')
+end

data/templates/api/docstring/html/text.erb

@@ -0,0 +1,6 @@
+<% untagged = object.tags.reject { |tag| tag.tag_name == 'API' }.empty? %>
+
+<% text = object.docstring.strip %>
+<% text = '*No documentation available yet.*' if text.empty? && untagged %>
+
+<%= html_markup_markdown(text) %>

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

@@ -0,0 +1,78 @@
+require 'pathname'
+
+include YARD::Templates::Helpers::ModuleHelper
+include YARD::Templates::Helpers::FilterHelper
+
+def init
+  options[:resources] = options[:objects].
+    group_by { |o| o.tags('API').first.text }.
+    sort_by  { |o| o.first }
+
+  build_json_objects_map
+  generate_assets
+  serialize_index
+  serialize_static_pages
+
+  options.delete(:objects)
+
+  options[:resources].each do |resource, controllers|
+    serialize_resource(resource, controllers)
+  end
+end
+
+def serialize(object)
+  options[:object] = object
+  Templates::Engine.with_serializer(object, options[:serializer]) do
+    T('layout').run(options)
+  end
+end
+
+def serialize_resource(resource, controllers)
+  options[:object] = resource
+  options[:controllers] = controllers
+  Templates::Engine.with_serializer("#{topicize resource}.html", options[:serializer]) do
+    T('layout').run(options)
+  end
+  options.delete(:controllers)
+end
+
+def serialize_index
+  options[:file] = api_options['readme']
+  serialize('index.html')
+  options.delete(:file)
+end
+
+def asset(path, content)
+  options[:serializer].serialize(path, content) if options[:serializer]
+end
+
+def generate_assets
+  asset_root = Pathname.new(File.dirname(__FILE__))
+  (Dir[asset_root + "css/**/*.css"] + Dir[asset_root + "js/**/*.js"]).each do |file|
+    file = Pathname.new(file).relative_path_from(asset_root).to_s
+    asset(file, file(file, true))
+  end
+end
+
+def serialize_static_pages
+  static_pages.each do |page|
+    options[:file] = page[:src]
+    serialize(page[:filename])
+    options.delete(:file)
+  end
+end
+
+def build_json_objects_map
+  options[:json_objects_map] = {}
+  options[:json_objects] = {}
+  options[:resources].each do |r,cs|
+    cs.each do |controller|
+      (controller.tags(:object) + controller.tags(:model)).each do |obj|
+        name, json = obj.text.split(%r{\n+}, 2).map(&:strip)
+        options[:json_objects_map][name] = topicize r
+        options[:json_objects][r] ||= []
+        options[:json_objects][r] << [name, json]
+      end
+    end
+  end
+end

data/templates/api/layout/html/footer.erb

@@ -0,0 +1,11 @@
+<div id="footer">
+  <p>
+    <% if api_options['footer_copyright'] %>
+      <%= api_options['footer_copyright'] %>
+    <% end %>
+
+    Generated on <%= Time.now.strftime("%c") %>
+  </p>
+
+  <%= api_options['footer_note'].to_s %>
+</div>