prmd 0.6.2 → 0.7.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZGYzNzgzNTU3YWQwMTRmNzI5ZTVkYThhMDQwMGJkZWQxM2IzODVkOA==
-  data.tar.gz: !binary |-
-    NGNlZDM3N2JkMzUxMmYyYjk1ZjUwNDYyMzMyYzg4MmY2NTE5MTkzOQ==
+SHA1:
+  metadata.gz: 92c67299c0bc9e4bec5141b516ec7fa78d841f6d
+  data.tar.gz: dbcdf2ec6712b37f5980904e998d7085d3ca6dc9
 SHA512:
-  metadata.gz: !binary |-
-    ZjVjMmE5MTNlYjk5ZjU1MzYyZGRjNzNhMTE2Nzk4NDE4NDkyMGIzMDRhMWZl
-    Yzg0OGM2MTAyMDcxMTgzYjhjYTAxMGM0MDU0MWJkYmUwNDRhNWVlMjhmNjU0
-    NGJkOGVhZGRiMjgxYmM3ZTIyMmRiNTdjNmZmMjRjYmZjMDJkOGU=
-  data.tar.gz: !binary |-
-    NDhjYTRmYTBjMmVlZDhiYTc2OGUzMGI4NGMzOGU1ODMxZjMxZmIzYzU2YTM0
-    ZjQ0ODJlNzYyMzEzZDY0NzY4YmJkM2EwNWZiY2E3NWU1NzkyNzk0MmUyNTg4
-    YjUzYTMyNzU3NWI4ODc5NWVkYzVhMmI0MTQzZjA1MTI0NWI0YTk=
+  metadata.gz: bc6d901ec87dc0df4882265c7d5f95210f5bcf2777dda10870366547aabe9b42a90adc8007fa872b925f35ac1b192237a1c2eaebe8464f3b4083cad8405e90a5
+  data.tar.gz: 2b117de96b7c80c06db4e7173d3954265531ab3f70df26512118854ea6025068e3d0852cc615f1c79a5da84bd5609a4c9ba95824f5292fef9ca41cfd393db06d

data/CONTRIBUTORS.md

@@ -1,14 +1,20 @@
 * Adel Qalieh <aqalieh95@gmail.com>
+* Alex Sergeyev <alex.sergeyev@gmail.com>
+* Arnold <arnoldcano@yahoo.com>
 * Brandur <brandur@heroku.com>
 * Brandur <brandur@mutelight.org>
 * Chris Continanza <christopher.continanza@gmail.com>
+* Corey Powell <mistdragon100@gmail.com>
 * Dan Peterson <dpiddy@gmail.com>
 * Dane Harrigan <dane.harrigan@gmail.com>
 * Eric J. Holmes <eric@ejholmes.net>
 * Ernesto Jiménez <me@ernesto-jimenez.com>
+* Jason Rudolph <github@jasonrudolph.com>
+* Juan Pablo Buritica <juanpablo@buritica.org>
 * Justin Halsall <justin@juice10.com>
 * Kousuke Ebihara <Kosuke_Ebihara@voyagegroup.com>
 * Kousuke Ebihara <kousuke@co3k.org>
+* Lucas Carvalho <lucas.carvalho@corp.globo.com>
 * Mark McGranaghan <mmcgrana@gmail.com>
 * Martin Seeler <developer@chasmo.de>
 * Matthew Conway <himself@mattonrails.com>
@@ -16,4 +22,6 @@
 * Scott Clasen <scott@heroku.com>
 * Timothée Peignier <timothee.peignier@tryphon.org>
 * Wesley Beary <geemus+github@gmail.com>
+* Wesley Beary <geemus@gmail.com>
+* Zack Shapiro <zack.shapiro@kontagent.com>
 * geemus <geemus@gmail.com>

data/Gemfile.lock

@@ -3,21 +3,21 @@ PATH
   specs:
     prmd (0.6.2)
       erubis (~> 2.7)
-      json_schema (~> 0.1)
+      json_schema (~> 0.3, >= 0.3.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     erubis (2.7.0)
-    json_schema (0.1.4)
-    minitest (5.3.2)
-    rake (10.2.2)
+    json_schema (0.3.1)
+    minitest (5.4.2)
+    rake (10.3.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.3)
-  minitest (~> 5.3)
+  minitest (~> 5.4)
   prmd!
-  rake (~> 10.2)
+  rake (~> 10.3)

data/README.md

@@ -1,4 +1,6 @@
-# Prmd
+# Prmd [![Travis Status](https://travis-ci.org/interagent/prmd.svg)](https://travis-ci.org/interagent/prmd)
+
+[![Gem Version](https://badge.fury.io/rb/prmd.svg)](http://badge.fury.io/rb/prmd)
 
 JSON Schema tooling: scaffold, verify, and generate documentation
 from JSON Schema documents.
@@ -21,7 +23,7 @@ described in [/docs/schemata.md](/docs/schemata.md).
 
 Install the command-line tool with:
 
-```console
+```bash
 $ gem install prmd
 ```
 
@@ -32,7 +34,7 @@ to the application's Gemfile:
 gem 'prmd'
 ```
 
-```console
+```bash
 $ bundle install
 ```
 
@@ -48,7 +50,7 @@ Prmd provides four main commands:
 
 Here's an example of using these commands in a typical workflow:
 
-```console
+```bash
 # Fill out the resource schemata
 $ mkdir -p schemata
 $ prmd init app  > schemata/app.json
@@ -80,25 +82,72 @@ $ prmd doc schema.json > schema.md
 
 # Render from schema
 
-```console
+```bash
 $ prmd render --template schemata.erb schema.json > schema.md
 ```
 
 Typically you'll want to prepend header and overview information to
 your API documentation. You can do this with the `--prepend` flag:
 
-```console
-$ prmd doc schema.json --prepend overview.md > schema.md
+```bash
+$ prmd doc --prepend overview.md schema.json > schema.md
 ```
 
 You can also chain commands together as needed, e.g.:
 
-```console
+```bash
 $ prmd combine --meta meta.json schemata/ | prmd verify | prmd doc --prepend overview.md > schema.md
 ```
 
 See `prmd <command> --help` for additional usage details.
 
+## Documentation rendering settings
+
+Out of the box you can supply a settings file (in either `JSON` or `YAML`) that will tweak the layout of your documentation.
+
+```bash
+$ prmd doc --settings config.json schema.json > schema.md
+```
+
+Available options (and their defaults)
+```json
+{
+  "doc": {
+    "url_style": "default", // can also be "json"
+    "disable_title_and_description": false // remove the title and the description, useful when using your own custom header
+  }
+}
+```
+
+## Use as rake task
+
+In addition, prmd can be used via rake tasks
+
+```ruby
+# Rakefile
+require 'prmd/rake_tasks/combine'
+require 'prmd/rake_tasks/verify'
+require 'prmd/rake_tasks/doc'
+
+namespace :schema do
+  Prmd::RakeTasks::Combine.new do |t|
+    t.options[:meta] = 'schema/meta.json'
+    t.paths << 'schema/schemata/api'
+    t.output_file = 'schema/api.json'
+  end
+
+  Prmd::RakeTasks::Verify.new do |t|
+    t.files << 'schema/api.json'
+  end
+
+  Prmd::RakeTasks::Doc.new do |t|
+    t.files = { 'schema/api.json' => 'schema/api.md' }
+  end
+end
+
+task default: ['schema:combine', 'schema:verify', 'schema:doc']
+```
+
 ## File Layout
 
 We suggest the following file layout for JSON schema related files:

data/Rakefile

@@ -1,8 +1,8 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.pattern = "test/**/*_test.rb"
+  t.pattern = 'test/**/*_test.rb'
 end
 
-task :default => :test
+task default: :test

data/bin/prmd

@@ -1,120 +1,6 @@
 #!/usr/bin/env ruby
 require 'optparse'
-require(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'prmd')))
+require 'prmd'
+require 'prmd/cli'
 
-options = {}
-
-commands = {
-  combine: OptionParser.new do |opts|
-    opts.banner = "prmd combine [options] <file or directory>"
-    opts.on("-m", "--meta meta.json", "Set defaults for schemata") do |m|
-      options[:meta] = m
-    end
-  end,
-  doc: OptionParser.new do |opts|
-    opts.banner = "prmd doc [options] <combined schema>"
-    opts.on("-p", "--prepend header,overview", Array, "Prepend files to output") do |p|
-      options[:prepend] = p
-    end
-    opts.on("-u", "--url-style json", String, "URL style to output (default/json)") do |s|
-      options[:style] = s
-    end
-    opts.on("-c", "--content-type application/json", String, "Content-Type header") do |c|
-      options[:content_type] = c
-    end
-  end,
-  init: OptionParser.new do |opts|
-    opts.banner = "prmd init [options] <resource name>"
-    opts.on("-y", "--yaml", "Generate YAML") do |y|
-      options[:yaml] = y
-    end
-  end,
-  render: OptionParser.new do |opts|
-    opts.banner = "prmd render [options] <combined schema>"
-    opts.on("-p", "--prepend header,overview", Array, "Prepend files to output") do |p|
-      options[:prepend] = p
-    end
-    opts.on("-t", "--template templates", String, "Use alternate template") do |t|
-      options[:template] = t
-    end
-  end,
-  verify: OptionParser.new do |opts|
-    opts.banner = "prmd verify [options] <combined schema>"
-  end
-}
-
-help_text = commands.values.map do |command|
-  "   #{command.banner}"
-end.join("\n")
-
-global = OptionParser.new do |opts|
-  opts.banner = "Usage: prmd [options] [command [options]]"
-  opts.separator "\nAvailable options:"
-  opts.on("--version", "Return version") do |opts|
-    puts "prmd #{Prmd::VERSION}"
-    exit(0)
-  end
-  opts.separator "\nAvailable commands:"
-  opts.separator help_text
-end
-
-if ARGV.empty?
-  puts global
-  exit(1)
-end
-global.order!
-
-command = ARGV.shift.to_sym
-option = commands[command]
-if option.nil?
-  puts global
-  exit(1)
-end
-
-if ARGV.empty? && $stdin.tty?
-  puts option
-  exit(1)
-end
-option.order!
-
-case command
-  when :combine
-    puts Prmd.combine(ARGV[0], options).to_s
-  when :doc
-    data = unless $stdin.tty?
-      $stdin.read
-    else
-      File.read(ARGV[0])
-    end
-    schema = Prmd::Schema.new(JSON.parse(data))
-
-    options[:template] = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'prmd', 'templates'))
-
-    puts Prmd.render(schema, options)
-  when :init
-    puts Prmd.init(ARGV[0], options)
-  when :render
-    data = unless $stdin.tty?
-      $stdin.read
-    else
-      File.read(ARGV[0])
-    end
-    schema = Prmd::Schema.new(JSON.parse(data))
-    puts Prmd.render(schema, options)
-  when :verify
-    data, errors = '', []
-    unless $stdin.tty?
-      data = $stdin.read
-      errors.concat(Prmd.verify(JSON.parse(data)))
-    else
-      data = JSON.parse(File.read(ARGV[0]))
-      Prmd.verify(data).each do |error|
-        errors << "#{ARGV[0]}: #{error}"
-      end
-    end
-    errors.each do |error|
-      $stderr.puts(error)
-    end
-    exit(1) unless errors.empty?
-    puts(data) unless $stdout.tty?
-end
+Prmd::CLI.run(ARGV.dup, bin: File.basename(__FILE__))

data/docs/schemata.md

@@ -18,7 +18,7 @@ We have opted to split apart the schema into individual resource schema and a ro
 Each schema MUST include some meta-data, which we cluster at the top of the file, including:
 
 * `description` - a description of the resource described by the schema
-* `id` - an id for this schema, it MUST be in the form `"schema/#{lower_case_singular_resource}"`
+* `id` - an id for this schema, it MUST be in the form `"schemata/#{lower_case_singular_resource}"`
 * `$schema` - defines what meta-schema is in use, it MUST be `http://json-schema.org/draft-04/hyper-schema`
 * `title` - title for this resource, it MUST be in the form `"#{title_case_API_name} - #{title_case_plural_resource}"`
 * `type` - the type(s) of this schema, it MUST be `["object"]`
@@ -74,7 +74,7 @@ The links array MUST include an object defining each action available. Each acti
 
 * `description` - a description of the action to perform
 * `href` - the path associated with this action, use [URI templates](http://tools.ietf.org/html/rfc6570) as needed, CGI escaping any JSON pointer values used for identity
-* `method` - the http method to be used with this actio
+* `method` - the http method to be used with this action
 * `rel` - describes relation of link to resource, SHOULD be one of `["create", "destroy", "self", "instances", "update"]`
 * `title` - title for the link
 
@@ -94,8 +94,8 @@ If this field is not present, all attributes in this link are considered as opti
       "rel":          "create",
       "schema":       {
         "properties": {
-          "owner":  { "$ref": "/schema/user#/definitions/identity" },
-          "url":    { "$ref": "/schema/resource/definitions/url" }
+          "owner":  { "$ref": "/schemata/user#/definitions/identity" },
+          "url":    { "$ref": "/schemata/resource/definitions/url" }
         },
         "required": [ "owner", "url" ]
       },
@@ -103,14 +103,14 @@ If this field is not present, all attributes in this link are considered as opti
     },
     {
       "description":  "Delete an existing resource.",
-      "href":         "/resources/{(%2Fschema%2Fresources%23%2Fdefinitions%2Fidentity)}",
+      "href":         "/resources/{(%2Fschemata%2Fresources%23%2Fdefinitions%2Fidentity)}",
       "method":       "DELETE",
       "rel":          "destroy",
       "title":        "Delete"
     },
     {
       "description":  "Info for existing resource.",
-      "href":         "/resources/{(%2Fschema%2Fresources%23%2Fdefinitions%2Fidentity)}",
+      "href":         "/resources/{(%2Fschemata%2Fresources%23%2Fdefinitions%2Fidentity)}",
       "method":       "GET",
       "rel":          "self",
       "title":        "Info"
@@ -124,12 +124,12 @@ If this field is not present, all attributes in this link are considered as opti
     },
     {
       "description":  "Update an existing resource.",
-      "href":         "/resources/{(%2Fschema%2Fresource%23%2Fdefinitions%2Fidentity)}",
+      "href":         "/resources/{(%2Fschemata%2Fresource%23%2Fdefinitions%2Fidentity)}",
       "method":       "PATCH",
       "rel":          "update",
       "schema":       {
         "properties": {
-          "url":    { "$ref": "/schema/resource/definitions/url" }
+          "url":    { "$ref": "/schemata/resource/definitions/url" }
         }
       },
       "title":        "Update"
@@ -146,15 +146,15 @@ The properties object MUST contain all the serialized attributes for the object.
 ```javascript
 {
   "properties": {
-    "id":       { "$ref": "/schema/resource#/definitions/id" },
+    "id":       { "$ref": "/schemata/resource#/definitions/id" },
     "owner": {
       "description": "unique identifier of the user who owns this resource",
       "properties": {
-        "id": { "$ref": "/schema/user#/definitions/id" }
+        "id": { "$ref": "/schemata/user#/definitions/id" }
       },
       "type": ["object"]
     },
-    "url":      { "$ref": "/schema/resource#/definitions/url" }
+    "url":      { "$ref": "/schemata/resource#/definitions/url" }
   }
 }
 ```

data/lib/prmd.rb

@@ -1,18 +1,7 @@
-require "cgi"
-require "erubis"
-require "json"
-require "yaml"
-
-dir = File.dirname(__FILE__)
-require File.join(dir, 'prmd', 'commands', 'combine')
-require File.join(dir, 'prmd', 'commands', 'expand')
-require File.join(dir, 'prmd', 'commands', 'init')
-require File.join(dir, 'prmd', 'commands', 'render')
-require File.join(dir, 'prmd', 'commands', 'verify')
-require File.join(dir, 'prmd', 'schema')
-require File.join(dir, 'prmd', 'version')
-require File.join(dir, 'prmd', 'template')
-require File.join(dir, 'prmd', 'url_generator')
-
-module Prmd
-end
+require 'prmd/version'
+require 'prmd/load_schema_file'
+require 'prmd/commands'
+require 'prmd/schema'
+require 'prmd/template'
+require 'prmd/url_generator'
+require 'prmd/hash_helpers'

data/lib/prmd/cli.rb

@@ -0,0 +1,108 @@
+require 'prmd/core_ext/optparse'
+require 'prmd/cli/combine'
+require 'prmd/cli/doc'
+require 'prmd/cli/generate'
+require 'prmd/cli/render'
+require 'prmd/cli/verify'
+
+# :nodoc:
+module Prmd
+  # Main CLI module
+  module CLI
+    # @param [Hash<Symbol, Object>] props
+    # @return [Hash<Symbol, OptionParser>] all dem parsers
+    def self.make_command_parsers(props = {})
+      {
+        combine: CLI::Combine.make_parser(props),
+        doc:     CLI::Doc.make_parser(props),
+        init:    CLI::Generate.make_parser(props),
+        render:  CLI::Render.make_parser(props),
+        verify:  CLI::Verify.make_parser(props)
+      }
+    end
+
+    # List of all available commands
+    #
+    # @return [Array] available commands
+    def self.commands
+      @commands ||= make_command_parsers.keys
+    end
+
+    # Creates the CLI main parser
+    #
+    # @param [Hash<Symbol, Object>] options
+    # @param [Hash<Symbol, Object>] props
+    def self.make_parser(options, props = {})
+      binname = props.fetch(:bin, 'prmd')
+
+      # This is only used to attain the help commands
+      commands = make_command_parsers(props)
+      help_text = commands.values.map do |command|
+        "   #{command.banner}"
+      end.join("\n")
+
+      global = OptionParser.new do |opts|
+        opts.banner = "Usage: #{binname} [options] [command [options]]"
+        opts.separator "\nAvailable options:"
+        opts.on('--version', 'Return version') do
+          puts "prmd #{Prmd::VERSION}"
+          exit(0)
+        end
+        opts.on('--noop', 'Commands will not execute') do |v|
+          options[:noop] = v
+        end
+        opts.separator "\nAvailable commands:"
+        opts.separator help_text
+      end
+
+      global
+    end
+
+    # Parse top level CLI options from argv
+    #
+    # @param [Array<String>] argv
+    # @param [Hash<Symbol, Object>] opts
+    # @return [Hash<Symbol, Object>] parsed options
+    def self.parse_options(argv, opts = {})
+      options = {}
+      parser = make_parser(options, opts)
+      abort parser if argv.empty?
+      com_argv = parser.order(argv)
+      abort parser if com_argv.empty?
+      command = com_argv.shift.to_sym
+      abort parser unless commands.include?(command)
+      options[:argv] = com_argv
+      options[:command] = command
+      options
+    end
+
+    # Execute the Prmd CLI, or its subcommands
+    #
+    # @param [Array<String>] uargv
+    # @param [Hash<Symbol, Object>] opts
+    # @return [void]
+    def self.run(uargv, opts = {})
+      options = parse_options(uargv, opts)
+      argv = options.delete(:argv)
+      command = options.delete(:command)
+
+      case command
+      when :combine
+        CLI::Combine.run(argv, options)
+      when :doc
+        CLI::Doc.run(argv, options)
+      when :init
+        CLI::Generate.run(argv, options)
+      when :render
+        CLI::Render.run(argv, options)
+      when :verify
+        CLI::Verify.run(argv, options)
+      end
+    end
+
+    class << self
+      private :make_command_parsers
+      private :commands
+    end
+  end
+end