grape_documenter 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/.gitignore ADDED
@@ -0,0 +1,17 @@
1
+ *.gem
2
+ *.rbc
3
+ .bundle
4
+ .config
5
+ .yardoc
6
+ Gemfile.lock
7
+ InstalledFiles
8
+ _yardoc
9
+ coverage
10
+ doc/
11
+ lib/bundler/man
12
+ pkg
13
+ rdoc
14
+ spec/reports
15
+ test/tmp
16
+ test/version_tmp
17
+ tmp
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source 'https://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in grape_doc.gemspec
4
+ gemspec
data/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ Copyright (c) 2012 Phil Lee
2
+
3
+ MIT License
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ "Software"), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,41 @@
1
+ # GrapeDoc
2
+
3
+ This adds a rake tasks to Rails Applications to generate documentation for Grape APIs.
4
+
5
+ ## Installation
6
+
7
+ Add this line to your application's Gemfile:
8
+
9
+ gem 'grape_doc'
10
+
11
+ And then execute:
12
+
13
+ $ bundle
14
+
15
+ Or install it yourself as:
16
+
17
+ $ gem install grape_doc
18
+
19
+ ## Usage
20
+
21
+ Within the root of you Rails Application run the following rake task...
22
+
23
+ $ bundle exec rake generate_grape_docs['MyApplication::API','/path/to/where/you/want/your/docs']
24
+
25
+ NOTE: The lack of space between the arguments. Rake doesn't like the space unless you wrap the whole thing as a string.
26
+
27
+ The first argument is the a string of the class of Grape::API. If you have multiple APIs within the same application you can run the rake task as many times as you like with different output paths.
28
+
29
+ ### Specifying output format
30
+
31
+ Currently 2 formats are supported: 'html'; 'textile'. The default is html. You can change the format as shown below...
32
+
33
+ $ bundle exec rake generate_grape_docs['MyApplication::API','/path/to/where/you/want/your/docs','textile']
34
+
35
+ ## Contributing
36
+
37
+ 1. Fork it
38
+ 2. Create your feature branch (`git checkout -b my-new-feature`)
39
+ 3. Commit your changes (`git commit -am 'Added some feature'`)
40
+ 4. Push to the branch (`git push origin my-new-feature`)
41
+ 5. Create new Pull Request
data/Rakefile ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env rake
2
+ require "bundler/gem_tasks"
data/grape_doc.gemspec ADDED
@@ -0,0 +1,23 @@
1
+ # -*- encoding: utf-8 -*-
2
+ require File.expand_path('../lib/grape_doc/version', __FILE__)
3
+
4
+ Gem::Specification.new do |gem|
5
+ gem.authors = ["Phil Lee", "Steven Anderson"]
6
+ gem.email = ["philip.lee@sage.com"]
7
+ gem.description = "This adds a rake tasks to Rails Applications to generate documentation for Grape APIs."
8
+ gem.summary = "This adds a rake tasks to Rails Applications to generate documentation for Grape APIs."
9
+ gem.homepage = ""
10
+
11
+ gem.files = `git ls-files`.split($\)
12
+ gem.executables = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
13
+ gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
14
+ gem.name = "grape_documenter"
15
+ gem.require_paths = ["lib"]
16
+ gem.version = GrapeDoc::VERSION
17
+
18
+ gem.add_dependency 'grape', '0.2.1'
19
+ gem.add_dependency 'RedCloth'
20
+ gem.add_dependency 'activesupport'
21
+
22
+ gem.add_development_dependency 'rspec'
23
+ end
@@ -0,0 +1,17 @@
1
+ require 'RedCloth'
2
+
3
+ module GrapeDoc
4
+ module Formatters
5
+ # For ease this uses the textile formatter first then post processes to html
6
+ class Html
7
+ def initialize(structure)
8
+ @structure = structure
9
+ end
10
+
11
+ def format
12
+ textile = Textile.new(@structure)
13
+ RedCloth.new(textile.format).to_html
14
+ end
15
+ end
16
+ end
17
+ end
@@ -0,0 +1,66 @@
1
+ require 'active_support/core_ext/object/blank'
2
+
3
+ module GrapeDoc
4
+ module Formatters
5
+ class Textile
6
+ def initialize(structure)
7
+ @structure = structure
8
+ end
9
+
10
+ def format
11
+ doc = @structure
12
+
13
+ output = "h1. #{doc.title}"
14
+ output << "\n\n"
15
+ output << resource_navigation
16
+ output << "\n\n"
17
+
18
+ doc.routes.each do |route|
19
+ output << "\n\n"
20
+ output << "h2. #{route.route_method}: #{route.route_path.gsub(':version', doc.version)}"
21
+ output << "\n\n"
22
+
23
+ if route.route_description.present?
24
+ output << "h3. Description"
25
+ output << "\n\n"
26
+ output << route.route_description
27
+ output << "\n\n"
28
+ end
29
+
30
+ if route.route_params.present?
31
+ output << "h3. Parameters"
32
+ output << "\n\n"
33
+ output << tabulate_params(route.route_params)
34
+ output << "\n\n"
35
+ end
36
+ end
37
+
38
+ output
39
+ end
40
+
41
+ private
42
+
43
+ def resource_navigation
44
+ depth = (@structure.root_path.count('/')-1)
45
+ navigation = ''
46
+
47
+ @structure.resources.each do |resource|
48
+ navigation << "* \"#{resource[:name]}\":#{'../' * depth}#{resource[:path].sub('/', '')}.html\n"
49
+ end
50
+
51
+ navigation
52
+ end
53
+
54
+ def tabulate_params(params)
55
+ string = "|_.Name|_.Type|_.Description|\n"
56
+
57
+ params.each do |k,v|
58
+ v = {:desc => v} unless v.is_a?(Hash)
59
+ string << "|#{k}|#{v[:type]}|#{v[:desc]}|\n"
60
+ end
61
+
62
+ string
63
+ end
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,89 @@
1
+ require 'fileutils'
2
+ require 'active_support/inflector'
3
+
4
+ module GrapeDoc
5
+ class Generator
6
+ def initialize(api_class, output_path, options = {})
7
+ raise 'api_class must be specified' if api_class.nil?
8
+ raise 'output_path must be specified' if output_path.nil?
9
+
10
+ @output_path = output_path
11
+ @api_class = api_class.constantize
12
+ @format = options[:format] || 'html'
13
+ end
14
+
15
+ def generate_namespace_docs
16
+ docs = []
17
+
18
+ @api_class.versions.each do |version|
19
+ namespaces_for_version(version).each do |namespace|
20
+ docs << NamespaceDoc.new(:version => version,
21
+ :title => titleize(namespace),
22
+ :root_path => namespace,
23
+ :routes => routes_for_version_and_namespace(version, namespace),
24
+ :resources => resources_for_version(version))
25
+ end
26
+ end
27
+
28
+ docs
29
+ end
30
+
31
+ def output
32
+ files = {}
33
+ generate_namespace_docs.each do |doc|
34
+ puts doc.title
35
+
36
+ filename = File.join(@output_path, doc.version, "#{doc.root_path}.#{@format}")
37
+ files[filename] = self.send("generate_#{@format}", doc)
38
+ end
39
+
40
+ Writer.new(files).write_to_files!
41
+ end
42
+
43
+ private
44
+
45
+ def generate_textile(doc)
46
+ Formatters::Textile.new(doc).format
47
+ end
48
+
49
+ def generate_html(doc)
50
+ Formatters::Html.new(doc).format
51
+ end
52
+
53
+ def resources_for_version(version)
54
+ resources = []
55
+ namespaces_for_version(version).each do |resource|
56
+ resources << { :name => titleize(resource), :path => resource }
57
+ end
58
+ resources
59
+ end
60
+
61
+ def namespaces_for_version(version)
62
+ return instance_variable_get("@#{version}_namespaces") if instance_variable_get("@#{version}_namespaces")
63
+
64
+ instance_variable_set("@#{version}_namespaces", routes_for_version(version).map { |r| normalize_route_namespace(r) }.uniq)
65
+ end
66
+
67
+ def normalize_route_namespace(route)
68
+ n = route.route_namespace
69
+ route.route_params.each do |p,_|
70
+ n.gsub!(":#{p.gsub('/', '')}", '')
71
+ end
72
+ n.gsub(/\/+/, '/')
73
+ end
74
+
75
+ def routes_for_version(version)
76
+ return instance_variable_get("@#{version}_routes") if instance_variable_get("@#{version}_routes")
77
+
78
+ instance_variable_set("@#{version}_routes", @api_class.routes.select { |r| r.route_version == version })
79
+ end
80
+
81
+ def routes_for_version_and_namespace(version, namespace)
82
+ routes_for_version(version).select { |r| normalize_route_namespace(r) == namespace }
83
+ end
84
+
85
+ def titleize(string)
86
+ string.split('/').last.titleize
87
+ end
88
+ end
89
+ end
@@ -0,0 +1,13 @@
1
+ module GrapeDoc
2
+ class NamespaceDoc
3
+ attr_accessor :title, :routes, :root_path, :version, :resources
4
+
5
+ def initialize(options = {})
6
+ @title = options[:title]
7
+ @routes = options[:routes]
8
+ @root_path = options[:root_path]
9
+ @version = options[:version]
10
+ @resources = options[:resources]
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,9 @@
1
+ require 'grape_doc'
2
+
3
+ module GrapeDoc
4
+ class Railtie < Rails::Railtie
5
+ rake_tasks do
6
+ load 'tasks/generate.rake'
7
+ end
8
+ end
9
+ end
@@ -0,0 +1,3 @@
1
+ module GrapeDoc
2
+ VERSION = "0.0.1"
3
+ end
@@ -0,0 +1,16 @@
1
+ module GrapeDoc
2
+ class Writer
3
+ def initialize(doc_structure)
4
+ @doc_structure = doc_structure
5
+ end
6
+
7
+ def write_to_files!
8
+ @doc_structure.each do |filename, contents|
9
+ FileUtils.mkdir_p(File.dirname(filename))
10
+ File.open(filename, 'w') do |f|
11
+ f.write(contents)
12
+ end
13
+ end
14
+ end
15
+ end
16
+ end
data/lib/grape_doc.rb ADDED
@@ -0,0 +1,10 @@
1
+ require "grape_doc/version"
2
+
3
+ module GrapeDoc
4
+ require 'grape_doc/generator'
5
+ require 'grape_doc/writer'
6
+ require 'grape_doc/namespace_doc'
7
+ require 'grape_doc/formatters/textile'
8
+ require 'grape_doc/formatters/html'
9
+ require 'grape_doc/railtie' if defined?(Rails)
10
+ end
@@ -0,0 +1,7 @@
1
+ require 'grape_doc'
2
+
3
+ desc "Generate documentation for Grape API"
4
+ task :generate_grape_docs, [:api_class, :output_path, :format] => :environment do |t, args|
5
+ generator = GrapeDoc::Generator.new(args[:api_class], args[:output_path], :format => args[:format])
6
+ generator.output
7
+ end
@@ -0,0 +1,39 @@
1
+ require 'spec_helper'
2
+
3
+ describe GrapeDoc::Formatters::Textile do
4
+ let(:mock_route) do
5
+ mock('route', :route_method => 'GET',
6
+ :route_path => '/users',
7
+ :route_description => 'users description goes here',
8
+ :route_params => {:id => {:type => 'integer', :desc => 'user id'}})
9
+ end
10
+
11
+ let(:structure) do
12
+ GrapeDoc::NamespaceDoc.new :version => 'v1',
13
+ :title => 'Users',
14
+ :root_path => '/users',
15
+ :routes => [mock_route],
16
+ :resources => [{ :name => 'Contacts', :path => '/contacts' }]
17
+ end
18
+
19
+ subject { described_class.new(structure) }
20
+
21
+ it 'has h1 with title' do
22
+ subject.format.should include('h1. Users')
23
+ end
24
+
25
+ it 'has an h2 with method and path' do
26
+ subject.format.should include('h2. GET: /users')
27
+ end
28
+
29
+ it 'has an h3 and the description' do
30
+ subject.format.should include('h3. Description')
31
+ subject.format.should include('users description goes here')
32
+ end
33
+
34
+ it 'has an h3 and the route_params in a table' do
35
+ subject.format.should include('h3. Parameters')
36
+ subject.format.should include('|_.Name|_.Type|_.Description|')
37
+ subject.format.should include('|id|integer|user id|')
38
+ end
39
+ end
@@ -0,0 +1,27 @@
1
+ require 'spec_helper'
2
+
3
+ describe GrapeDoc::Generator do
4
+ subject { described_class.new 'MyApplication::API', '/tmp/grape_doc' }
5
+
6
+ context 'for a given api version' do
7
+ it 'stores the version' do
8
+ subject.generate_namespace_docs.first.version.should == 'v1'
9
+ end
10
+
11
+ it 'stores the title' do
12
+ subject.generate_namespace_docs.first.title.should == 'User'
13
+ end
14
+
15
+ it 'stores the root_path' do
16
+ subject.generate_namespace_docs.first.root_path.should == '/user'
17
+ end
18
+
19
+ it 'stores the routes' do
20
+ subject.generate_namespace_docs.first.routes.should == MyApplication::API.routes.select{|r| r.route_version == 'v1'}
21
+ end
22
+
23
+ it 'stores the global resources' do
24
+ subject.generate_namespace_docs.first.resources.should == [{ :name => 'User', :path => '/user' }]
25
+ end
26
+ end
27
+ end
@@ -0,0 +1,2 @@
1
+ require 'grape_doc'
2
+ require 'support/test_api'
@@ -0,0 +1,37 @@
1
+ require 'grape'
2
+
3
+ module MyApplication
4
+ class API < Grape::API
5
+ version 'v1' do
6
+ resource :user do
7
+ desc 'Get all users'
8
+ get do
9
+ end
10
+
11
+ desc 'Get the specified user', :params => {
12
+ 'id' => { :desc => 'The id of the user', :type => 'integer' }
13
+ }
14
+ get ':id' do
15
+ end
16
+ end
17
+ end
18
+
19
+ version 'v2' do
20
+ resource :user do
21
+ desc 'Get all users'
22
+ get do
23
+ end
24
+
25
+ desc 'Get the specified user', :params => {
26
+ 'id' => { :desc => 'The id of the user', :type => 'integer' }
27
+ }
28
+ get ':id' do
29
+ end
30
+
31
+ resource :comments do
32
+
33
+ end
34
+ end
35
+ end
36
+ end
37
+ end
metadata ADDED
@@ -0,0 +1,136 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: grape_documenter
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.1
5
+ prerelease:
6
+ platform: ruby
7
+ authors:
8
+ - Phil Lee
9
+ - Steven Anderson
10
+ autorequire:
11
+ bindir: bin
12
+ cert_chain: []
13
+ date: 2012-08-15 00:00:00.000000000 Z
14
+ dependencies:
15
+ - !ruby/object:Gem::Dependency
16
+ name: grape
17
+ requirement: !ruby/object:Gem::Requirement
18
+ none: false
19
+ requirements:
20
+ - - '='
21
+ - !ruby/object:Gem::Version
22
+ version: 0.2.1
23
+ type: :runtime
24
+ prerelease: false
25
+ version_requirements: !ruby/object:Gem::Requirement
26
+ none: false
27
+ requirements:
28
+ - - '='
29
+ - !ruby/object:Gem::Version
30
+ version: 0.2.1
31
+ - !ruby/object:Gem::Dependency
32
+ name: RedCloth
33
+ requirement: !ruby/object:Gem::Requirement
34
+ none: false
35
+ requirements:
36
+ - - ! '>='
37
+ - !ruby/object:Gem::Version
38
+ version: '0'
39
+ type: :runtime
40
+ prerelease: false
41
+ version_requirements: !ruby/object:Gem::Requirement
42
+ none: false
43
+ requirements:
44
+ - - ! '>='
45
+ - !ruby/object:Gem::Version
46
+ version: '0'
47
+ - !ruby/object:Gem::Dependency
48
+ name: activesupport
49
+ requirement: !ruby/object:Gem::Requirement
50
+ none: false
51
+ requirements:
52
+ - - ! '>='
53
+ - !ruby/object:Gem::Version
54
+ version: '0'
55
+ type: :runtime
56
+ prerelease: false
57
+ version_requirements: !ruby/object:Gem::Requirement
58
+ none: false
59
+ requirements:
60
+ - - ! '>='
61
+ - !ruby/object:Gem::Version
62
+ version: '0'
63
+ - !ruby/object:Gem::Dependency
64
+ name: rspec
65
+ requirement: !ruby/object:Gem::Requirement
66
+ none: false
67
+ requirements:
68
+ - - ! '>='
69
+ - !ruby/object:Gem::Version
70
+ version: '0'
71
+ type: :development
72
+ prerelease: false
73
+ version_requirements: !ruby/object:Gem::Requirement
74
+ none: false
75
+ requirements:
76
+ - - ! '>='
77
+ - !ruby/object:Gem::Version
78
+ version: '0'
79
+ description: This adds a rake tasks to Rails Applications to generate documentation
80
+ for Grape APIs.
81
+ email:
82
+ - philip.lee@sage.com
83
+ executables: []
84
+ extensions: []
85
+ extra_rdoc_files: []
86
+ files:
87
+ - .gitignore
88
+ - Gemfile
89
+ - LICENSE
90
+ - README.md
91
+ - Rakefile
92
+ - grape_doc.gemspec
93
+ - lib/grape_doc.rb
94
+ - lib/grape_doc/formatters/html.rb
95
+ - lib/grape_doc/formatters/textile.rb
96
+ - lib/grape_doc/generator.rb
97
+ - lib/grape_doc/namespace_doc.rb
98
+ - lib/grape_doc/railtie.rb
99
+ - lib/grape_doc/version.rb
100
+ - lib/grape_doc/writer.rb
101
+ - lib/tasks/generate.rake
102
+ - spec/formatters/textile_spec.rb
103
+ - spec/generator_spec.rb
104
+ - spec/spec_helper.rb
105
+ - spec/support/test_api.rb
106
+ homepage: ''
107
+ licenses: []
108
+ post_install_message:
109
+ rdoc_options: []
110
+ require_paths:
111
+ - lib
112
+ required_ruby_version: !ruby/object:Gem::Requirement
113
+ none: false
114
+ requirements:
115
+ - - ! '>='
116
+ - !ruby/object:Gem::Version
117
+ version: '0'
118
+ required_rubygems_version: !ruby/object:Gem::Requirement
119
+ none: false
120
+ requirements:
121
+ - - ! '>='
122
+ - !ruby/object:Gem::Version
123
+ version: '0'
124
+ requirements: []
125
+ rubyforge_project:
126
+ rubygems_version: 1.8.24
127
+ signing_key:
128
+ specification_version: 3
129
+ summary: This adds a rake tasks to Rails Applications to generate documentation for
130
+ Grape APIs.
131
+ test_files:
132
+ - spec/formatters/textile_spec.rb
133
+ - spec/generator_spec.rb
134
+ - spec/spec_helper.rb
135
+ - spec/support/test_api.rb
136
+ has_rdoc: