dictum 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d6c5ff3c6e60436b079a7686e5ac902c0667dd16
-  data.tar.gz: 1e01d5c17f6c352d49f3b701dc6f574ad5bbad81
+  metadata.gz: e544707e273d694375827f0032d4ee924dff02d9
+  data.tar.gz: df5bea103157a87699791ff558464f3bf4693f4d
 SHA512:
-  metadata.gz: 5d10b7d5b8a4f91682e0a40424bae391b1c12269e6b4b6080d90cb73ebe9e8ec62a26529b2e002df6b8f189d2fa5317f76db87d67fdbb1176d578cd4842512c5
-  data.tar.gz: af6203c9ea677dca51c9fbf1fe14b7dc451d36ef3c745a51f795ce7d209c603a1df1f0198dfa150b24254734956e7858720486e5350b672197b20aa301a84c0b
+  metadata.gz: fdfbb27c664eb351c72eab2617c6bc5cca57be8e8cb9aa72cc17c42bbecc0738fb187a7830ecf9d513520a408cd544b8e3ecfcb35ca694effb22ec237dc49556
+  data.tar.gz: 50187a697fd04d757580bb00ecbfe4cafc60fe8a6f6559b1ab9c22e2b52816a9097126e86e0607d2ee4f1f1968f6e203799ac123af5aacb3ccf4dd40cc200ee0

data/README.md

@@ -23,23 +23,24 @@ Or install it yourself as:
 
     $ gem install dictum
 
-## Usage
+## Basic usage
 
 First you need to set a configuration file inside /config/initializers/dictum.rb
 
 ```ruby
+# /config/initializers/dictum.rb
 Dictum.configure do |config|
   config.output_path = Rails.root.join('docs')
   config.root_path = Rails.root
   config.output_filename = 'Documentation'
-  # config.output_format = :markdown
-  # test_suite = :rspec
+  config.output_format = :markdown
 end
 ```
 
 Then you can use Dictum in the most verbose and fully customizable way like this in your tests:
 
 ```ruby
+# spec/controllers/my_resource_controller_spec.rb
 require 'rails_helper'
 
 describe V1::MyResourceController do
@@ -72,9 +73,62 @@ describe V1::MyResourceController do
   end
 end
 ```
-Most parameters are not mandatory, and as you can see, writing all of these for each endpoint can add a lot of unnecessary boilerplate. But since you know everything the method receives you can customize the usage anyway you like, for example:
+
+Then execute:
+
+    $ bundle exec rake dictum:document
+
+And voilà, Dictum will create a document like this in '/docs/Documentation':
+
+    # Index
+    - MyResource
+
+    # MyResource
+    This is MyResource description.
+
+    ## POST /api/v1/my_resource
+
+    ### Description:
+    Some description of the endpoint.
+
+    ### Request headers:
+    ```json
+    {
+      "AUTHORIZATION" : "user_token",
+      "Content-Type" : "application/json",
+      "Accept" : "application/json"
+    }
+    ```
+
+    ### Path parameters:
+    ```json
+    { "id": 1, "page": 1 }
+    ```
+
+    ### Body parameters:
+    ```json
+    { "some": "parameter" }
+    ```
+
+    ### Response headers:
+    ```json
+    { "some_header": "some_header_value" }
+    ```
+
+    ### Response status:
+    200
+
+    ### Response body:
+    ```json
+    "no_content"
+    ```
+
+# Advanced usage
+
+If you pay attention to the basic usage, you will notice that much code is needed if your API has a lot of endpoints, this is not DRY and adds unnecesary boilerplate. Luckily you can work around it using some Rspec tricks:
 
 ```ruby
+# spec/controllers/my_resource_controller_spec.rb
 require 'rails_helper'
 
 describe V1::MyResourceController do
@@ -112,39 +166,74 @@ describe V1::MyResourceController do
 end
 ```
 
-Then execute:
+This is much better, but it is not DRYed enough because you would have to repeat the after(:each) declaration on every controller spec you have, so you can still improve it a bit more:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.after(:each) do |test|
+    if test.metadata[:dictum]
+      Dictum.endpoint(
+        # All the parameters that you want
+      )
+    end
+  end
+end
+end
+```
 
-    $ bundle exec dictum
+```ruby
+# spec/controllers/my_resource_controller_spec.rb
+require 'rails_helper'
 
-Both ways Dictum will create a document like this:
+describe V1::MyResourceController do
+  Dictum.resource(
+    name: 'MyResource',
+    description: 'This is MyResource description.'
+  )
 
-    # Index
-    - MyResource
+  describe '#some_method' do
+    context 'some context for my resource' do
+      it 'returns status ok', dictum: true, dictum_description: 'Some description of the endpoint.' do
+        get :index
+        expect(response_status).to eq(200)
+      end
+    end
+  end
+end
+```
 
-    # MyResource
-    This is MyResource description.
+# Dynamic HTML documentation
 
-    ## GET /api/v1/my_resource
+So far so good, but your team needs to read the documentation everytime you update it, and sending the documentation file to them doesn't seem too practical. Instead you can use the HTML version of Dictum and generate static views with the content. Here is a very basic example of what you can do to generate the views and routes dynamycally:
 
-    ### Description:
-    Some description of the endpoint.
+```ruby
+# /config/initializers/dictum.rb
+Dictum.configure do |config|
+  config.output_path = Rails.root.join('app', 'views')
+  config.root_path = Rails.root
+  config.output_filename = 'docs'
+  config.output_format = :html
+end
+```
 
-    ### Request headers:
-    ```json
-    {
-      "AUTHORIZATION" : "user_token",
-      "Content-Type" : "application/json",
-      "Accept" : "application/json"
-    }
-    ```
+Here we are telling Dictum to generate the HTML documentation in 'app/views/docs', where it will put one HTML file per resource you have defined. Now that we have the files, lets create the routes for them:
 
-    ### Response status:
-    200
+```ruby
+# config/routes.rb
+YourApp::Application.routes.draw do
+  #
+  # Other routes defined
+  #
+  
+  doc_paths = Dir["#{Rails.root.join('app', 'views', 'docs')}/*"].each do |path|
+    resource = path.split('/').last.gsub('.html', '')
+    get "/docs/#{resource}", to: "docs##{resource}"
+  end
+end
+```
 
-    ### Response body:
-    ```json
-    "no_content"
-    ```
+Of course you will need to have a controller for this, in this case one named 'docs_controller.rb'. And finally go to 'http://localhost:3000/docs/index.html'
 
 ## Contributing
 

data/lib/dictum.rb

@@ -1,6 +1,8 @@
 require 'dictum/version'
 require 'dictum/documenter'
 require 'dictum/markdown_writer'
+require 'dictum/html_writer'
+require 'dictum/html_helpers'
 
 module Dictum
   load 'tasks/dictum.rake' if defined?(Rails)
@@ -57,17 +59,24 @@ module Dictum
   def self.document
     Dir.mkdir(@config[:output_path]) unless Dir.exist?(@config[:output_path])
     Documenter.instance.reset_resources
+
     system "bundle exec rspec #{@config[:root_path]}" if @config[:test_suite] == :rspec
+
     save_to_file
   end
 
   def self.save_to_file
     writer = nil
+    output_filename = "#{@config[:output_path]}/#{@config[:output_filename]}"
+    tempfile_path = Documenter.instance.tempfile_path
+
     case @config[:output_format]
     when :markdown
-      writer = MarkdownWriter.new("#{@config[:output_path]}/#{@config[:output_filename]}.md",
-                                  Documenter.instance.tempfile_path)
+      writer = MarkdownWriter.new(output_filename, tempfile_path)
+    when :html
+      writer = HtmlWriter.new(output_filename, tempfile_path, 'Dictum')
     end
+
     writer.write
   end
 end

data/lib/dictum/html_helpers.rb

@@ -0,0 +1,85 @@
+module Dictum
+  class HtmlHelpers
+    BOOTSTRAP_JS = 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js'.freeze
+    BOOTSTRAP_CSS = 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css'.freeze
+    JQUERY = 'https://code.jquery.com/jquery-1.12.2.min.js'.freeze
+    PRETTIFY = 'https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js'.freeze
+
+    class << self
+      def html_header(title)
+        "<!DOCTYPE html>\n<html>\n<head>\n<title>#{title}</title>\n#{external_css(BOOTSTRAP_CSS)}"\
+        "\n<style>\n#{page_css}\n</style>\n</head>\n<body>\n"
+      end
+
+      def html_footer
+        "#{script(JQUERY)}\n#{script(BOOTSTRAP_JS)}\n#{script(PRETTIFY)}\n</body>\n</html>"
+      end
+
+      def page_css
+        ''
+      end
+
+      def container
+        "<div class='container-fluid'>\n"
+      end
+
+      def container_end
+        '</div>'
+      end
+
+      def row
+        "<div class='row'>\n<div class='col-md-8 col-md-offset-2'>\n"
+      end
+
+      def row_end
+        "</div>\n</div>"
+      end
+
+      def script(text)
+        "<script src='#{text}'></script>"
+      end
+
+      def external_css(text)
+        "<link rel='stylesheet' href='#{text}'>"
+      end
+
+      def unordered_list(elements)
+        answer = "<ul>\n"
+        elements.each do |element|
+          answer += "<li><a href='#{element.downcase}.html'>#{element}</a></li>\n"
+        end
+        answer += '</ul>'
+      end
+
+      def title(text, html_class = nil)
+        "<h1 class='#{html_class}'>#{text}</h1>"
+      end
+
+      def subtitle(text, html_class = nil)
+        "<h3 class='#{html_class}'>#{text}</h3>"
+      end
+
+      def paragraph(text, html_class = nil)
+        "<p class='#{html_class}'>#{text}</p>"
+      end
+
+      def button(text, glyphicon = nil)
+        "<a href='index.html'><button type='button' class='btn btn-primary back'" \
+        "aria-label='Left Align'><span class='glyphicon #{glyphicon}' aria-hidden='true'>" \
+        "</span>#{text}</button></a>"
+      end
+
+      def code_block(title, json)
+        "#{sub_subtitle(title)}\n#{code(json)}"
+      end
+
+      def sub_subtitle(text, html_class = nil)
+        "<h4 class='#{html_class}'>#{text}</h4>"
+      end
+
+      def code(json)
+        "<pre class='prettyprint'>#{json}</pre>"
+      end
+    end
+  end
+end

data/lib/dictum/html_writer.rb

@@ -0,0 +1,108 @@
+require_relative 'html_helpers'
+require 'json'
+
+module Dictum
+  class HtmlWriter
+    attr_reader :temp_path, :temp_json, :output_dir, :output_file, :output_title
+
+    def initialize(output_dir, temp_path, output_title)
+      @output_dir = output_dir
+      @temp_path = temp_path
+      @temp_json = JSON.parse(File.read(temp_path))
+      @output_title = output_title
+    end
+
+    def write
+      Dir.mkdir(output_dir) unless Dir.exist?(output_dir)
+      write_index
+      write_pages
+    end
+
+    private
+
+    def write_index_header(file)
+      return unless file
+      file.puts(HtmlHelpers.html_header(output_title))
+      file.puts(HtmlHelpers.container)
+      file.puts(HtmlHelpers.row)
+    end
+
+    def write_index_footer(file)
+      return unless file
+      file.puts(HtmlHelpers.row_end)
+      file.puts(HtmlHelpers.container_end)
+      file.puts(HtmlHelpers.html_footer)
+    end
+
+    def write_index
+      index = File.open("#{output_dir}/index.html", 'w+')
+      write_index_header(index)
+      index.puts("<div class='jumbotron'>\n#{HtmlHelpers.title('Index', 'title')}\n</div>")
+      index.puts(HtmlHelpers.unordered_list(temp_json.keys))
+      write_index_footer(index)
+      index.close
+    end
+
+    def write_pages_header(resource_name, text, file)
+      write_index_header(file)
+      file.puts(HtmlHelpers.title(resource_name, 'title'))
+      file.puts(HtmlHelpers.paragraph(text))
+    end
+
+    def write_pages_footer(file)
+      return unless file
+      file.puts(HtmlHelpers.row_end)
+      file.puts(HtmlHelpers.row)
+      file.puts(HtmlHelpers.button('Back', 'glyphicon-menu-left'))
+      write_index_footer(file)
+    end
+
+    def write_pages
+      temp_json.each do |resource_name, information|
+        file = File.open("#{output_dir}/#{resource_name.downcase}.html", 'w+')
+        write_pages_header(resource_name, information['description'], file)
+
+        write_endpoints(information['endpoints'], file)
+
+        write_pages_footer(file)
+        file.close
+      end
+    end
+
+    def write_endpoints(endpoints, file)
+      endpoints.each do |endpoint|
+        file.puts HtmlHelpers.subtitle("#{endpoint['http_verb']} #{endpoint['endpoint']}")
+        file.puts HtmlHelpers.paragraph(endpoint['description'])
+        write_request_parameters(endpoint, file)
+        write_response(endpoint, file)
+      end
+    end
+
+    def write_request_parameters(endpoint, file)
+      write_codeblock('Request headers', JSON.pretty_generate(endpoint['request_headers']), file)
+      write_codeblock('Request path parameters',
+                      JSON.pretty_generate(endpoint['request_path_parameters']), file)
+      write_codeblock('Request body parameters',
+                      JSON.pretty_generate(endpoint['request_body_parameters']), file)
+    end
+
+    def write_response(endpoint, file)
+      write_codeblock('Status', endpoint['response_status'], file)
+      write_codeblock(
+        'Response headers',
+        JSON.pretty_generate(endpoint['response_headers']),
+        file
+      ) if endpoint['response_headers']
+
+      if endpoint['response_body']
+        param = (endpoint['response_body'] == 'no_content') ? {} : endpoint['response_body']
+        write_codeblock('Response body', JSON.pretty_generate(param), file)
+      end
+    end
+
+    def write_codeblock(text, json, file)
+      return unless text && json && file
+      file.puts HtmlHelpers.code_block(text, json)
+    end
+  end
+end

data/lib/dictum/markdown_writer.rb

@@ -5,7 +5,7 @@ module Dictum
     attr_reader :temp_path, :temp_json, :output_path, :output_file
 
     def initialize(output_path, temp_path)
-      @output_path = output_path
+      @output_path = "#{output_path}.md"
       File.delete(output_path) if File.exist?(output_path)
       @temp_path = temp_path
       @temp_json = JSON.parse(File.read(temp_path))

data/lib/dictum/version.rb

@@ -1,3 +1,3 @@
 module Dictum
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.0.3'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dictum
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Alejandro Bezdjian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-15 00:00:00.000000000 Z
+date: 2016-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,6 +108,8 @@ files:
 - dictum.gemspec
 - lib/dictum.rb
 - lib/dictum/documenter.rb
+- lib/dictum/html_helpers.rb
+- lib/dictum/html_writer.rb
 - lib/dictum/markdown_writer.rb
 - lib/dictum/version.rb
 - lib/tasks/dictum.rake
@@ -131,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Document your APIs.