dox 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fd403721b5cfc4b7c0b7e1ac2c5605b9dc2eb935
-  data.tar.gz: 5717471c12c20d20c0e2cf33ebbdf46a4c89e57c
+  metadata.gz: 77769eb7c66afabb92fdfd03814b9ba19fd4c532
+  data.tar.gz: 810167221ebe04073d1a33f5eecc6db0f9683589
 SHA512:
-  metadata.gz: c8106a3112d98b5418d4cee81cebe6038f006c6d77fdf94ea0dd0d02aefef2741b0c6e4d7b43839dbd6e79e971a89869dca61545fc9e00082d2abdc9c6873654
-  data.tar.gz: cccfa6d0735c1e94f0eac444fcbd07563bd364d86491ea4e3283b331862c024ba5fce0cdfebe080daf5aa88176b3561fdb6ac87fe7b97609660a1a3106a6c727
+  metadata.gz: 47deb48ed84dbd87868adb2b360e77e3a7ecf3762e607a23e13af2024e262c8ab2b1f81a837efcca5fff386490a66f0c6b7d36100f00974738b4a3cb5380be7b
+  data.tar.gz: 10e5dd7824ded8945f169d9336cb0413d60121b6b4656332e43e5c860f452c073b8f9f32411dbf6cdfcb21799ba8b7f3c7add4de27979828c4c1597942267be2

data/README.md

@@ -1,8 +1,6 @@
 # Dox
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/dox`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Dox formats the rspec output in the [api blueprint](https://apiblueprint.org/) format.
 
 ## Installation
 
@@ -22,7 +20,94 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Code example
+
+Example documentation module for a resource:
+
+``` ruby
+module ApiDoc
+  module V1
+    module Bids
+      include Dox::DSL::Syntax
+
+      document :api do
+        group do
+          name 'Bids'
+        end
+
+        resource do
+          name 'Bids'
+          endpoint '/bids'
+          group 'Bids'
+          desc 'bid_resource.md'
+        end
+      end
+
+      document :index do
+        action do
+          name 'Get bids'
+          verb 'GET'
+          path '/bids'
+          desc 'Returns list of user bids'
+        end
+      end
+
+      document :create do
+        action do
+          name 'Post bids'
+          verb 'POST'
+          path '/bids'
+          desc 'Creates bid'
+        end
+      end
+    end
+  end
+end
+```
+Description can be included inline or relative path of a markdown file with the description (relative to configured folder for markdown descriptions).
+
+Including the documentation module in a controller:
+
+``` ruby
+describe Api::V1::BidsController, type: :controller do
+  include ApiDoc::V1::Bids::Api
+
+  describe 'GET #index' do
+    include ApiDoc::V1::Bids::Index
+
+    it 'returns a list of bids' do
+      get :index
+      expect(response).to have_http_status(:ok)
+    end
+
+  end
+end
+```
+
+### Configuration
+
+You have to specify **root api file** and **descriptions folder**.
+
+Root api file is a markdown file that will be included in the top of the documentation. It should contain title and some basic info about the api.
+
+Descriptions folder is a fullpath of a folder that contains markdown files with descriptions which behave like partials and are included in the final concatenated markdown. Root api file should also be in this folder.
+
+``` ruby
+Dox.configure do |config|
+  config.root_api_file = 'api.md'
+  config.desc_folder_path = Rails.root.join('spec/support/api_doc/v1/markdown_descriptions')
+end
+```
+
+### Generate HTML documentation
+You have to install [aglio](https://www.npmjs.com/package/aglio).
+
+Rake task for generating HTML:
+
+``` ruby
+  `bundle exec rspec spec --tag apidoc -f Dox::Formatter --order defined --out spec/apispec.md`
+  `aglio --include-path / -i spec/apispec.md -o public/api/docs/index.html`
+```
 
 ## Development
 

data/lib/dox.rb

@@ -1,5 +1,35 @@
+require "rspec/rails"
 require "dox/version"
+require "dox/config"
+require "dox/formatter"
+require "dox/dsl/attr_proxy"
+require "dox/dsl/action"
+require "dox/dsl/resource"
+require "dox/dsl/resource_group"
+require "dox/dsl/documentation"
+require "dox/dsl/syntax"
+require "dox/entities/action"
+require "dox/entities/example"
+require "dox/entities/resource"
+require "dox/entities/resource_group"
+require "dox/printers/base_printer"
+require "dox/printers/action_printer"
+require "dox/printers/document_printer"
+require "dox/printers/example_printer"
+require "dox/printers/resource_group_printer"
+require "dox/printers/resource_printer"
+
 
 module Dox
-  # Your code goes here...
+  class << self
+    attr_writer :config
+  end
+
+  def self.configure
+    yield(config) if block_given?
+  end
+
+  def self.config
+    @conifg ||= Dox::Config.new
+  end
 end

data/lib/dox/config.rb

@@ -0,0 +1,13 @@
+module Dox
+  class Config
+
+    attr_accessor :root_api_file, :desc_folder_path
+
+    def initialize
+      @root_api_file = 'api.md'
+      @desc_folder_path = Rails.root.join('')
+    end
+
+  end
+end
+

data/lib/dox/dsl/action.rb

@@ -0,0 +1,35 @@
+module Dox
+  module DSL
+    class Action
+      include AttrProxy
+
+      attr_writer :name
+      attr_writer :verb
+      attr_writer :path
+      attr_writer :desc
+      attr_writer :params
+
+      def initialize(opts = {})
+        self.name = opts.fetch(:name, nil)
+        self.verb = opts.fetch(:verb, nil)
+        self.path = opts.fetch(:path, nil)
+        self.desc = opts.fetch(:desc, nil)
+        self.params = opts.fetch(:params, nil)
+      end
+
+      def param(signature)
+        params << signature
+      end
+
+      def config
+        Hash.new.tap do |config|
+          config[:action_name] = @name if @name
+          config[:action_verb] = @verb if @verb
+          config[:action_path] = @path if @path
+          config[:action_desc] = @desc if @desc
+          config[:action_params] = @params if @params
+        end
+      end
+    end
+  end
+end

data/lib/dox/dsl/attr_proxy.rb

@@ -0,0 +1,12 @@
+module Dox
+  module DSL
+    module AttrProxy
+      def method_missing(name, value)
+        setter = "#{name.to_s}="
+        return super unless respond_to? setter
+
+        public_send setter, value
+      end
+    end
+  end
+end

data/lib/dox/dsl/documentation.rb

@@ -0,0 +1,35 @@
+module Dox
+  module DSL
+    class Documentation
+      attr_accessor :subject
+      attr_accessor :_resource
+      attr_accessor :_action
+      attr_accessor :_group
+
+      def initialize(opts = {})
+        self.subject = opts.fetch :subject
+      end
+
+      def resource(name = nil, &block)
+        self._resource = Resource.new(name: name)
+        _resource.instance_eval(&block)
+      end
+
+      def action(name = nil, &block)
+        self._action = Action.new(name: name)
+        _action.instance_eval(&block)
+      end
+
+      def group(name = nil, &block)
+        self._group = ResourceGroup.new(name: name)
+        _group.instance_eval(&block)
+      end
+
+      def config
+        {}.merge(_resource ? _resource.config : {})
+          .merge(_action ? _action.config : {})
+          .merge(_group ? _group.config : {})
+      end
+    end
+  end
+end

data/lib/dox/dsl/resource.rb

@@ -0,0 +1,29 @@
+module Dox
+  module DSL
+    class Resource
+      include AttrProxy
+
+      attr_writer :name
+      attr_writer :group
+      attr_writer :desc
+      attr_writer :endpoint
+
+      def initialize(opts = {})
+        self.name = opts.fetch(:name, nil)
+        self.desc = opts.fetch(:desc, nil)
+        self.group = opts.fetch(:group, nil)
+        self.endpoint = opts.fetch(:endpoint, nil)
+      end
+
+      def config
+        {}.tap do |config|
+          config[:resource_name] = @name if @name
+          config[:resource_desc] = @desc if @desc
+          config[:resource_group_name] = @group if @group
+          config[:resource_endpoint] = @endpoint if @endpoint
+          config[:apidoc] = true
+        end
+      end
+    end
+  end
+end

data/lib/dox/dsl/resource_group.rb

@@ -0,0 +1,23 @@
+module Dox
+  module DSL
+    class ResourceGroup
+      include AttrProxy
+
+      attr_writer :name
+      attr_writer :desc
+
+      def initialize(opts = {})
+        self.name = opts.fetch(:name, nil)
+        self.desc = opts.fetch(:desc, nil)
+      end
+
+      def config
+        {}.tap do |config|
+          config[:resource_group_name] = @name if @name
+          config[:resource_group_desc] = @desc if @desc
+          config[:apidoc] = true
+        end
+      end
+    end
+  end
+end

data/lib/dox/dsl/syntax.rb

@@ -0,0 +1,33 @@
+module Dox
+  module DSL
+    module Syntax
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def document(subject, &block)
+          documentation = _subjects[subject] = Documentation.new(subject: subject)
+          documentation.instance_eval(&block)
+        end
+
+        def const_missing(name)
+          documentation = _subjects[infer_subject(name)]
+          return super unless documentation
+
+          Module.new do
+            define_singleton_method :included do |base|
+              base.metadata.merge! documentation.config
+            end
+          end
+        end
+
+        def infer_subject(name)
+          name.to_s.underscore.to_sym
+        end
+
+        def _subjects
+          @_subjects ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/dox/entities/action.rb

@@ -0,0 +1,18 @@
+module Dox
+  module Entities
+    class Action
+
+      attr_accessor :name, :desc, :verb, :path, :uri_params, :examples
+
+      def initialize(name, details)
+        @name = name
+        @desc = details[:action_desc]
+        @verb = details[:action_verb]
+        @path = details[:action_path]
+        @uri_params = details[:action_params]
+        @examples = []
+      end
+
+    end
+  end
+end

data/lib/dox/entities/example.rb

@@ -0,0 +1,52 @@
+module Dox
+  module Entities
+    class Example
+
+      attr_reader :desc, :request, :response
+
+      def initialize(details, request, response)
+        @desc = details[:description]
+        @request = request
+        @response = response
+      end
+
+      def request_parameters
+        request.parameters.except(*request.path_parameters.keys.map(&:to_s)).except(*request.query_parameters.keys.map(&:to_s))
+      end
+
+      def request_content_type
+        request.content_type
+      end
+
+      def request_identifier
+        fullpath
+      end
+
+      def response_status
+        response.status
+      end
+
+      def response_content_type
+        response.content_type
+      end
+
+      def response_body
+        response.body
+      end
+
+      private
+
+      def path
+        request.path.sub(/\.json[^\?]*/, '')
+      end
+
+      def fullpath
+        if request.query_parameters.present?
+          URI::HTTP.build(path: path, query: request.query_parameters.to_query)
+        else
+          path
+        end
+      end
+    end
+  end
+end

data/lib/dox/entities/resource.rb

@@ -0,0 +1,16 @@
+module Dox
+  module Entities
+    class Resource
+
+      attr_accessor :name, :desc, :endpoint, :actions
+
+      def initialize(name, details)
+        @name = name
+        @desc = details[:resource_desc]
+        @endpoint = details[:resource_endpoint]
+        @actions = {}
+      end
+
+    end
+  end
+end

data/lib/dox/entities/resource_group.rb

@@ -0,0 +1,15 @@
+module Dox
+  module Entities
+    class ResourceGroup
+
+      attr_reader :name
+      attr_accessor :desc, :resources
+
+      def initialize(name, details)
+        @name = name
+        @desc = details[:resource_group_desc]
+        @resources = {}
+      end
+    end
+  end
+end

data/lib/dox/formatter.rb

@@ -0,0 +1,86 @@
+require 'rspec/core/formatters/base_formatter'
+require 'pry'
+
+module Dox
+  class Formatter < RSpec::Core::Formatters::BaseFormatter
+
+    RSpec::Core::Formatters.register self, :example_passed, :example_started, :stop
+
+    def initialize(output)
+      super
+      @passed_examples = {}
+      @group_level = 0
+    end
+
+    def example_started(notification)
+      @example_group_instance = notification.example.example_group_instance
+    end
+
+    def example_passed(passed)
+      @current_example_data = passed.example.metadata
+      if should_document_example?
+        move_example_to_passed
+      end
+      @example_group_instance = nil
+    end
+
+    def stop(_notification)
+      printer.print(@passed_examples)
+    end
+
+    private
+
+    def load_or_save_group
+      group_name = @current_example_data[:resource_group_name]
+      group = @passed_examples[group_name]
+
+      if group
+        group.desc ||= @current_example_data[:resource_group_desc]
+        group
+      else
+        @passed_examples[group_name] = Entities::ResourceGroup.new(group_name, @current_example_data)
+      end
+    end
+
+    def load_or_save_resource_to_group(group)
+      resource_name = @current_example_data[:resource_name]
+      group.resources[resource_name] ||= Entities::Resource.new(resource_name, @current_example_data)
+    end
+
+    def load_or_save_action_to_resource(resource)
+      action_name = @current_example_data[:action_name]
+      resource.actions[action_name] ||= Entities::Action.new(action_name, @current_example_data)
+    end
+
+    def move_example_to_passed
+      group = load_or_save_group
+      resource = load_or_save_resource_to_group(group)
+      action = load_or_save_action_to_resource(resource)
+      action.examples << Entities::Example.new(@current_example_data, request, response)
+    end
+
+    def should_document_example?
+      @current_example_data[:apidoc] &&
+        !@current_example_data[:nodoc]
+      # error check
+      #&&
+        # @current_example_data[:resource_group] &&
+        # @current_example_data[:resource] &&
+        # @current_example_data[:action] &&
+        # !@current_example_data[:nodoc]
+    end
+
+    def request
+      @example_group_instance.request
+    end
+
+    def response
+      @example_group_instance.response
+    end
+
+    def printer
+      @printer ||= Printers::DocumentPrinter.new(output)
+    end
+
+  end
+end

data/lib/dox/printers/action_printer.rb

@@ -0,0 +1,31 @@
+module Dox
+  module Printers
+    class ActionPrinter < BasePrinter
+
+      def print(action)
+        @output.puts "### #{action.name}\n\n#{print_desc(action.desc)}\n\n"
+
+        if action.uri_params.present?
+          @output.puts("+ Parameters\n#{formatted_params(action.uri_params)}")
+        end
+
+        action.examples.each do |example|
+          example_printer.print(example)
+        end
+      end
+
+      private
+
+      def example_printer
+        @example_printer ||= ExamplePrinter.new(@output)
+      end
+
+      def formatted_params(uri_params)
+        uri_params.map do |param, details|
+          "    + #{CGI.escape(param.to_s)}: `#{CGI.escape(details[:value].to_s)}` (#{details[:type]}, #{details[:required]}) - #{details[:description]}"
+        end.flatten.join("\n")
+      end
+
+    end
+  end
+end

data/lib/dox/printers/base_printer.rb

@@ -0,0 +1,31 @@
+module Dox
+  module Printers
+    class BasePrinter
+
+      attr_reader :descriptions_folder_path
+
+      def initialize(output)
+        @output = output
+        @descriptions_folder_path = Dox.config.desc_folder_path
+      end
+
+      def print
+        raise NotImplementedError
+      end
+
+      private
+
+      def print_desc(desc)
+        return unless desc.present?
+
+        if desc.to_s =~ /.*\.md$/
+          path = descriptions_folder_path.join(desc).to_s
+          "<!-- include(#{path}) -->"
+        else
+          desc
+        end
+      end
+
+    end
+  end
+end

data/lib/dox/printers/document_printer.rb

@@ -0,0 +1,29 @@
+module Dox
+  module Printers
+    class DocumentPrinter < BasePrinter
+
+      def print(passed_examples)
+        print_meta_info
+
+        passed_examples.sort.each do |_, resource_group|
+          group_printer.print(resource_group)
+        end
+      end
+
+      private
+
+      def group_printer
+        @group_printer ||= ResourceGroupPrinter.new(@output)
+      end
+
+      def print_meta_info
+        @output.puts(print_desc(api_desc_path))
+      end
+
+      def api_desc_path
+        Dox.config.root_api_file
+      end
+
+    end
+  end
+end

data/lib/dox/printers/example_printer.rb

@@ -0,0 +1,41 @@
+module Dox
+  module Printers
+    class ExamplePrinter < BasePrinter
+
+      def print(example)
+        @output.puts "\n+ Request #{example.request_identifier} (#{example.request_content_type})"
+
+        if example.request_parameters.present?
+          @output.puts "\n#{indent_lines(8, pretty_json(example.request_parameters))}\n"
+        end
+
+        @output.puts "+ Response #{example.response_status} (#{example.response_content_type})"
+
+        if example.response_body.present?
+          @output.puts "\n#{indent_lines(8, pretty_json(safe_json_parse(example.response_body)))}\n"
+        end
+      end
+
+      private
+
+      def safe_json_parse(json_string)
+        json_string.length >= 2 ? JSON.parse(json_string) : nil
+      end
+
+      def pretty_json(json_string)
+        if json_string.present?
+          JSON.pretty_generate(json_string)
+        else
+          ''
+        end
+      end
+
+      def indent_lines(number_of_spaces, string)
+        string
+          .split("\n")
+          .map { |a| a.prepend(' ' * number_of_spaces) }
+          .join("\n")
+      end
+    end
+  end
+end

data/lib/dox/printers/resource_group_printer.rb

@@ -0,0 +1,21 @@
+module Dox
+  module Printers
+    class ResourceGroupPrinter < BasePrinter
+
+      def print(resource_group)
+        @output.puts "\n# Group #{resource_group.name}\n\n#{print_desc(resource_group.desc)}\n"
+
+        resource_group.resources.each do |_, resource|
+          resource_printer.print(resource)
+        end
+      end
+
+      private
+
+      def resource_printer
+        @resource_printer ||= ResourcePrinter.new(@output)
+      end
+
+    end
+  end
+end

data/lib/dox/printers/resource_printer.rb

@@ -0,0 +1,25 @@
+module Dox
+  module Printers
+    class ResourcePrinter < BasePrinter
+
+      def print(resource)
+        if resource.endpoint.present?
+          @output.puts "\n## #{resource.name} [#{resource.endpoint}]\n\n#{print_desc(resource.desc)}\n"
+        else
+          @output.puts "## #{resource.name}"
+        end
+
+        resource.actions.each do |_, action|
+          action_printer.print(action)
+        end
+      end
+
+      private
+
+      def action_printer
+        @action_printer ||= ActionPrinter.new(@output)
+      end
+
+    end
+  end
+end

data/lib/dox/version.rb

@@ -1,3 +1,3 @@
 module Dox
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dox
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Melita Kokot
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-06 00:00:00.000000000 Z
+date: 2016-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -71,6 +71,24 @@ files:
 - bin/setup
 - dox.gemspec
 - lib/dox.rb
+- lib/dox/config.rb
+- lib/dox/dsl/action.rb
+- lib/dox/dsl/attr_proxy.rb
+- lib/dox/dsl/documentation.rb
+- lib/dox/dsl/resource.rb
+- lib/dox/dsl/resource_group.rb
+- lib/dox/dsl/syntax.rb
+- lib/dox/entities/action.rb
+- lib/dox/entities/example.rb
+- lib/dox/entities/resource.rb
+- lib/dox/entities/resource_group.rb
+- lib/dox/formatter.rb
+- lib/dox/printers/action_printer.rb
+- lib/dox/printers/base_printer.rb
+- lib/dox/printers/document_printer.rb
+- lib/dox/printers/example_printer.rb
+- lib/dox/printers/resource_group_printer.rb
+- lib/dox/printers/resource_printer.rb
 - lib/dox/version.rb
 homepage: https://github.com/infinum/dox
 licenses:
@@ -98,4 +116,3 @@ signing_key:
 specification_version: 4
 summary: Generates API documentation for rspec in api blueprint format.
 test_files: []
-has_rdoc: