prmd 0.1.0 → 0.1.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OTJiYjFkZjYwZTAxYWExOTJmYzAxMWZjYmJiNmQ1YzA3ZTdiMmY0Ng==
+    NmYyYTg0MjRlYWQwZjBlZjFlMGU2OTVjODUyODYyZDQxOTZjMDgyNA==
   data.tar.gz: !binary |-
-    Y2RmMDI2NTIyNzQxZTk4NjcxZmZhYzU5NTM2NDdlNmM4YWZhMTE4Mg==
+    MjNiZDJhNzdhMDU1M2MyYTNjOTViODgxMGJkZTMyNGY2YTRhODcwMg==
 SHA512:
   metadata.gz: !binary |-
-    MTE2N2FhODUzYjgxY2Y0YjJmOGUwYzRkYTQwYmY0Nzg2NDJhNDdjM2JhZGYy
-    ZjFjY2MxMGY5ZmNkYjM0OTVlMmUyNTYzMGJlYTdmYjk1MTczOTZiODI3ZjVh
-    MWZlYTQ2OTg2MWRlNjg3Yjc4ZmU2MThkMGVjNTc2Yjg5ZGZmMTA=
+    ZmI5ZDU5ZTBkMGNmODQyYWNkYmY4Y2IxMTJlY2QxMGYwNTgyY2MwZDI0Njg0
+    OTczYTU2ZDI0ODBjZTJkNGIxMTQwYTUwNDdkNzA5ZmMzNjM5ZTgyNzlmYzEy
+    YjI3YmNiYjkxYzVlNmU3NDc1ZDQ1ZTMzZDliODZhZDcyNWI0NGU=
   data.tar.gz: !binary |-
-    ZjIyMmNlZmI2NGJiMjY2OGE5NWM2ZTJmMzkxMzAyM2NjNTkyOWFmMDZiMTRk
-    MWEwOWUwYmY0YjM3Mzk1N2FhNDE1YTdkYWJiNTY1NmUxMTE0NmQ4YjBiOTVm
-    Mjk5NzNmODZiNTIwNWUzY2Q3MDIxMjM0ZTRmNTEyMDFjMWU0MWY=
+    OTEyYTllYzkzODRkYWM3ODQ2NGM0MTA1Y2UyMjRiNDA4ZjMxZDUzMzI3YTRj
+    MjQyYTc1NmMyMWJmZTY4MTMxMDQ0OWYxYjBlZTNkMmVhYjAyNGQ2Yzc1Njg4
+    NjcyZWZiMGM0MTZhODc4Y2U1ZWNjNTIzNjFhOTQ1NzI4ZTZlN2I=

data/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+## Getting Involved
+
+New contributors are always welcome, when it doubt please ask questions. We strive to be an open and welcoming community. Please be nice to one another.
+
+### Coding
+
+* Pick a task:
+  * Offer feedback on open [pull requests](https://github.com/heroku/prmd/pulls).
+  * Review open [issues](https://github.com/heroku/prmd/issues) for things to help on.
+  * [Create an issue](https://github.com/heroku/prmd/issues/new) to start a discussion on additions or features.
+* Fork the project, add your changes and tests to cover them in a topic branch.
+* Commit your changes and rebase against `heroku/prmd` to ensure everything is up to date.
+* [Submit a pull request](https://github.com/heroku/prmd/compare/).
+
+### Non-Coding
+
+* Offer feedback on open [issues](https://github.com/heroku/prmd/issues).
+* Organize or volunteer at events.

data/CONTRIBUTORS.md

@@ -1,6 +1,8 @@
 * Brandur <brandur@mutelight.org>
 * Chris Continanza <christopher.continanza@gmail.com>
+* Dane Harrigan <dane.harrigan@gmail.com>
 * Mark McGranaghan <mmcgrana@gmail.com>
+* Olivier Lance <olance@users.noreply.github.com>
 * Timothée Peignier <timothee.peignier@tryphon.org>
 * Wesley Beary <geemus+github@gmail.com>
 * geemus <geemus@gmail.com>

data/Gemfile.lock

@@ -1,21 +1,21 @@
 PATH
   remote: .
   specs:
-    prmd (0.0.1)
-      erubis
+    prmd (0.1.0)
+      erubis (~> 2.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
     erubis (2.7.0)
-    minitest (4.7.5)
-    rake (10.1.0)
+    minitest (5.3.2)
+    rake (10.2.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.3)
-  minitest
+  minitest (~> 5.3)
   prmd!
-  rake
+  rake (~> 10.2)

data/README.md

@@ -1,7 +1,7 @@
 # Prmd
 
 JSON Schema tooling: scaffold, verify, and generate documentation
-against JSON Schema documents.
+from JSON Schema documents.
 
 
 ## Introduction
@@ -11,76 +11,100 @@ an API. prmd provides tools for bootstrapping a description like this,
 verifying its completeness, and generating documentation from the
 specification.
 
-The JSON Schema usage conventions expected by prmd are described in
-[/docs/schemata.md](/docs/schemata.md).
-
 To learn more about JSON Schema in general, start with
 [this excellent guide](http://spacetelescope.github.io/understanding-json-schema/)
 and supplement with the [specification](http://json-schema.org/documentation.html).
+The JSON Schema usage conventions expected by prmd specifically are
+described in [/docs/schemata.md](/docs/schemata.md).
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install the command-line tool with:
 
-```ruby
-gem 'prmd'
+```console
+$ gem install prmd
 ```
 
-And then execute:
+If you're using prmd within a Ruby project, you may want to add it
+to the application's Gemfile:
 
-```console
-$ bundle
+```ruby
+gem 'prmd'
 ```
 
-Or install it yourself as:
-
 ```console
-$ gem install prmd
+$ bundle install
 ```
 
 ## Usage
 
-Combine takes the path to a schema file or directory of schema files and
-combines them on to stdout. If -m or --meta is supplied, it will override
-defaults/metadata:
+Prmd provides four main commands:
 
-```console
-$ prmd combine <file or directory>
-```
+* `init`: Scaffold resource schemata
+* `combine`: Combine schemata and metadata into single schema
+* `verify`: Verify a schema
+* `doc`: Generate documentation from a schema
 
-Doc takes the path to a combined schema and outputs documentation to stdout.
-If -m or --meta is supplied, it will override defaults/metadata:
+Here's an example of using these commands in a typical workflow:
 
 ```console
-$ prmd doc <combined schema>
+# Fill out the resource schemata
+$ mkdir -p schemata
+$ prmd init app  > schemata/app.json
+$ prmd init user > schemata/user.json
+$ vim schemata/{app,user}.json   # edit scaffolded files
+
+# Provide top-level metadata
+$ cat <<EOF > meta.json
+{
+ "description": "Hello world prmd API",
+ "id": "hello-prmd",
+ "links": [{
+   "href": "https://api.hello.com",
+   "rel": "self"
+ }],
+ "title": "Hello Prmd"
+}
+EOF
+
+# Combine into a single schema
+$ prmd combine --meta meta.json schemata/ > schema.json
+
+# Check it’s all good
+$ prmd verify schema.json
+
+# Build docs
+$ prmd doc schema.json > schema.md
 ```
 
-You can also prepend files to the documention with -p or --prepend:
+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 -p header.md,overview.md <directory or schema>
+$ prmd doc schema.json --prepend overview.md > schema.md
 ```
 
-Init optionally takes a resource as it's first argument and generates a
-new schema file to stdout (generically or using the resource name
-provided). If -m or --meta is supplied, it will override
-defaults/metadata:
+You can also chain commands together as needed, e.g.:
 
 ```console
-$ prmd init
-$ prmd init <resource name>
+$ prmd combine --meta meta.json schemata/ | prmd verify | prmd doc --prepend overview.md > schema.md
 ```
 
-Verify takes a path to a combined schema and warns about missing attributes.
+See `prmd <command> --help` for additional usage details.
 
-```console
-$ prmd verify <combined schema>
-```
+## File Layout
 
-You can also chain commands as needed:
+We suggest the following file layout for JSON schema related files:
 
-```console
-$ prmd combine <directory> | prmd verify | prmd doc > schema.md
+```
+/docs (top-level directory for project documentation)
+  /schema (API schema documentation)
+    /schemata
+      /{resource.json} (individual resource schema)
+    /meta.json (overall API metadata)
+    /overview.md (preamble for generated API docs)
+    /schema.json (complete generated JSON schema file)
+    /schema.md (complete generated API documentation file)
 ```
 
 ## Contributing

data/bin/prmd

@@ -19,9 +19,6 @@ commands = {
   end,
   init: OptionParser.new do |opts|
     opts.banner = "prmd init [options] <resource name>"
-    opts.on("-m", "--meta meta.json", "Set defaults for schemata") do |m|
-      options[:meta] = m
-    end
   end,
   verify: OptionParser.new do |opts|
     opts.banner = "prmd verify [options] <combined schema>"

data/lib/prmd/commands/init.rb

@@ -10,10 +10,6 @@ module Prmd
       'type'        => ['object']
     }
 
-    if options[:meta] && File.exists?(options[:meta])
-      data.merge!(JSON.parse(File.read(options[:meta])))
-    end
-
     schema = Prmd::Schema.new(data)
 
     if resource
@@ -21,7 +17,7 @@ module Prmd
         parent, resource = resource.split('/')
       end
       schema['id']    = "schemata/#{resource}"
-      schema['title'] = "#{schema['title']} - #{resource[0...1].upcase}#{resource[1..-1]}"
+      schema['title'] = "FIXME - #{resource[0...1].upcase}#{resource[1..-1]}"
       schema['definitions'] = {
         "created_at" => {
           "description" => "when #{resource} was created",

data/lib/prmd/version.rb

@@ -1,3 +1,3 @@
 module Prmd
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/prmd/views/endpoint.erb

@@ -64,6 +64,7 @@ end -%>
     data = {}
     if link['schema']['properties']
       link['schema']['properties'].each do |key, value|
+        _, value = schema.dereference(value)
         if value.has_key?('anyOf')
           id_ref = value['anyOf'].detect {|ref| ref['$ref'].split('/').last == 'id'}
           data[key] = schema.dereference(id_ref).last['example']

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prmd
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - geemus
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-10 00:00:00.000000000 Z
+date: 2014-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: erubis
@@ -76,6 +76,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- CONTRIBUTING.md
 - CONTRIBUTORS.md
 - Gemfile
 - Gemfile.lock