apiaryio 0.3.1 → 0.3.2

data/README.md

@@ -1,81 +1,170 @@
-apiaryio
-=============
+Apiary CLI Client
+=================
 
-Apiary.io CLI
+[Apiary](https://apiary.io) CLI client, `apiary`.
 
 [![Build Status](https://travis-ci.org/apiaryio/apiary-client.png?branch=master)](https://travis-ci.org/apiaryio/apiary-client) [![Build status](https://ci.appveyor.com/api/projects/status/0hmkivbnhf9p3f8d/branch/master?svg=true)](https://ci.appveyor.com/project/Apiary/apiary-client/branch/master)
 
+## Description
+
+The Apiary CLI Client gem is a command line tool for developing and previewing
+[API Blueprint](http://apiblueprint.org) documents locally. It can also be
+used for pushing updated documents to and fetching existing documents from
+[Apiary](http://apiary.io).
+
+
+Please see the `apiary help` command and the [full documentation](http://client.apiary.io) for an in-depth look in how to use this tool.
+
+For instructions on making your  own changes, see [Hacking Apiary CLI Client](#hacking-apiary-cli-client), below.
+
+## Installation
 
-## Install
+### Install as a Ruby gem
 
-**install gem** (required)
-``` bash
+``` sh
 gem install apiaryio
 ```
 
-**setup APIARY.io credentials** (required for publish and fetch command only)
+### Setup Apiary credentials
 
-1. Retrieve APIKEY on `https://login.apiary.io/tokens`
-2. Save it to your environment variables :
+*Required only for publish and fetch commands.*
 
-```bash
-export APIARY_API_KEY=<your_token_retrieved_on_step_1>
+
+1. Make sure you are a registered user of [Apiary](http://apiary.io).
+2. Retrieve API key (token) on [this page](https://login.apiary.io/tokens).
+3. Export it as an environment variable:
+
+```sh
+export APIARY_API_KEY=<your_token>
 ```
+## Command-line Usage
 
-## Description
+```
+$ apiary help
+Commands:
+  apiary fetch --api-name=API_NAME    # Fetch apiary.apib from API_NAME.apiary.io
+  apiary help [COMMAND]               # Describe available commands or one specific command
+  apiary preview                      # Show API documentation in default browser
+  apiary publish --api-name=API_NAME  # Publish apiary.apib on docs.API_NAME.apiary.io
+  apiary version                      # Show version
 
-The Apiary CLI gem is a command line tool for developing and previewing
-API Blueprint documents locally. It can also be used for pushing
-updated documents to and fetching existing documents from Apiary.io.
+```
 
-Please see the [full documentation](http://client.apiary.io) for an in-depth
-look in how to use this tool.
+### Details
 
-## Usage
+#### fetch
 
-    $ apiary help
+```
+$ apiary help fetch
+Usage:
+  apiary fetch --api-name=API_NAME
 
-    Usage: apiary command [options]
-    Try 'apiary help' for more information.
+Options:
+  --api-name=API_NAME  
+  [--api-host=HOST]    # Specify apiary host
+  [--output=FILE]      # Write apiary.apib into specified file
 
-    Currently available apiary commands are:
+Fetch apiary.apib from API_NAME.apiary.io
+```
+
+#### preview
 
-      preview                                     Show API documentation in default browser
-      preview --browser [chrome|safari|firefox]   Show API documentation in specified browser
-      preview --output [FILE]                     Write generated HTML into specified file
-      preview --path [PATH]                       Specify path to blueprint file
-      preview --api_host [HOST]                   Specify apiary host
-      preview --server                            Start standalone web server on port 8080
-      preview --server --port [PORT]              Start standalone web server on specified port
-      publish --api-name [API_NAME]               Publish apiary.apib on docs.API_NAME.apiary.io
-      publish --api-name [API_NAME] \
-              --message [COMMIT_MESSAGE]          Publish with custom commit message
-      fetch   --api-name [API_NAME]               Fetch apiary.apib from API_NAME.apiary.io
-              --output [FILE]                     Write apiary.apib into specified file
-      help                                        Show this help
-      version                                     Show version
+```
+$ apiary help preview
+Usage:
+  apiary preview
+
+Options:
+  [--browser=chrome|safari|firefox]  # Show API documentation in specified browser
+                                     # Possible values: chrome, safari, firefox
+  [--output=FILE]                    # Write generated HTML into specified file
+  [--path=PATH]                      # Specify path to blueprint file
+                                     # Default: apiary.apib
+  [--api-host=HOST]                  # Specify apiary host
+  [--server], [--no-server]          # Start standalone web server on port 8080
+  [--port=PORT]                      # Set port for --server option
+
+Show API documentation in default browser
+```
 
-## Copyright
+#### publish
 
-Copyright 2012-15 (c) Apiary Ltd.
+```
+$ apiary help publish
+Usage:
+  apiary publish --api-name=API_NAME
+
+Options:
+  [--message=COMMIT_MESSAGE]  # Publish with custom commit message
+  [--path=PATH]               # Specify path to blueprint file
+                              # Default: apiary.apib
+  [--api-host=HOST]           # Specify apiary host
+  --api-name=API_NAME         
+
+Publish apiary.apib on docs.API_NAME.apiary.io
+```
+
+#### version
+
+```
+$ apiary help version
+Usage:
+  apiary version
+
+Options:
+  [--{:aliases=>"-v"}={:ALIASES=>"-V"}]  
+
+Show version
+```
+
+## Hacking Apiary CLI Client
+
+### Build
+
+1.  If needed, install bundler:
+
+    ```sh
+    $ gem install bundler
+    ```
+
+2.  Clone the repo:
+
+    ```sh
+    $ git clone git@github.com:apiaryio/apiary-client.git
+    $ cd apiary-client
+    ```
+
+3.  Install dependencies:
+
+    ```sh
+    $ bundle install
+    ```
+
+### Test
+
+Inside the `apiary-client` repository directory run:
+
+```sh
+$ bundle exec rake test
+$ bundle exec rake features
+```
+
+
+### Release
+
+Use `bundle install` to install your changes locally, for manual and ad-hock testing.
+
+Only gem owners `gem owner apiaryio` can publish new gem into [RubyGems](https://rubygems.org/gems/apiaryio).
+
+```sh
+$ rake release
+```
 
-## Contributors
-
-- Jakub Nešetřil
-- James Charles Russell [botanicus]
-- Lukáš Linhart [Almad]
-- Emili Parreño
-- Peter Grilli [Tu1ly]
-- Ladislav Prskavec
-- Honza Javorek
-- Matthew Rudy Jacobs
-- Adam Kliment
-- Jack Repenning
-- Peter Strapp
-- Pierre Merlin
-- František Hába
-- Benjamin Arthur Lupton
 
 ## License
 
-Released under MIT license. See LICENSE file for further details.
+Copyright 2012-15 (c) Apiary Ltd.
+
+Released under MIT license.
+See [LICENSE](https://raw.githubusercontent.com/apiaryio/apiary-client/master/LICENSE) file for further details.
+

data/apiary.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
   gem.version       = Apiary::VERSION
 
   gem.add_dependency "rest-client", "~> 1.8"
-  gem.add_dependency "rack", "~> 1.6"
+  gem.add_dependency "rack", "~> 1.6.4"
   gem.add_dependency "rake", "~> 10.4"
   gem.add_dependency "thor", "~> 0.19.1"
 

data/features/fetch.feature

@@ -1,7 +1,8 @@
 Feature: Fetch apiary.apib from API_NAME.apiary.io
 
   # This is integration testing you have to set APIARY_API_KEY
+  @needs_apiary_api_key
   Scenario: Fetch apiary.apib from API_NAME.apiary.io
 
-    When I run `apiary fetch --api-name apiaryclienttest`
+    When I run `apiary fetch --api-name testingapiaryclitestingapiarycli`
     Then the output should contain the content of file "apiary.apib"

data/features/preview.feature

@@ -1,6 +1,7 @@
 Feature: Show API documentation in specified browser
 
   # This is integration testing you have to set APIARY_API_KEY
+  @needs_apiary_api_key
   Scenario: Write generated HTML into specified file
 
     When I run `apiary preview --path apiary.apib --output=test.html`

data/features/publish.feature

@@ -1,7 +1,9 @@
 Feature: Publish apiary.apib on docs.API_NAME.apiary.io
 
   # This is integration testing you have to set APIARY_API_KEY
+  @needs_apiary_api_key
   Scenario: Publish apiary.apib on docs.API_NAME.apiary.io
 
+    # expected to fail
     When I run `apiary publish --path=apiary.apib --api-name 1111apiaryclienttest`
     Then the exit status should be 1

data/features/support/env.rb

@@ -4,4 +4,19 @@ require 'fileutils'
 Before do
   @dirs << "../../features/fixtures"
   ENV['PATH'] = "./bin#{File::PATH_SEPARATOR}#{ENV['PATH']}"  
-end
+end
+
+Around('@needs_apiary_api_key') do |scenario, block|
+  # DEBUG puts "Scenario #{scenario.name} wants APIARY_API_KEY."
+  original_value = ENV.delete("APIARY_API_KEY");
+  ENV["APIARY_API_KEY"] = "340bda135034529ab2abf341295c3aa2" # XXX
+  block.call
+  ENV["APIARY_API_KEY"] = original_value
+end
+
+Around('@doesnt_need_apiary_api_key') do |scenario, block|
+  # DEBUG puts "Scenario #{scenario.name} doesn't want APIARY_API_KEY."
+  original_value = ENV.delete("APIARY_API_KEY");
+  block.call
+  ENV["APIARY_API_KEY"] = original_value
+end

data/features/support/setup.rb

@@ -1 +1,5 @@
 require 'aruba/cucumber'
+
+Before('@needs_apiary_api_key') do
+  @aruba_timeout_seconds = 45
+end

data/features/version.feature

@@ -1,5 +1,6 @@
 Feature: Version of Apiary client
 
+  @doesnt_need_apiary_api_key
   Scenario: Print the semantic version of Apiary client
 
     # Note the output should be a semantic version (semver.org)

data/lib/apiary/version.rb

@@ -1,3 +1,3 @@
 module Apiary
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/spec/cli_spec.rb

@@ -2,8 +2,40 @@ require 'spec_helper'
 
 describe Apiary::CLI do
 
-  it 'pass the test' do
-    expect(true).to be_truthy
+  # Don't let Thor fold or truncate lines
+  ENV['THOR_COLUMNS'] = '1000'
+
+  # The documentation that ought to match the code
+  READMETEXT = open("README.md") {|f| f.read}
+
+  it 'has help' do
+    help = open('|ruby bin/apiary help') {|f| f.read}
+    expect(help).to include("Commands:")
+    expect(help.lines.count).to be >= 5
   end
 
+  it 'has README.md' do
+    expect(READMETEXT).to include("apiary help")
+    expect(READMETEXT.lines.count).to be >= 5
+  end
+
+  # Confirm that all subcommands are documented, verbatim
+  ([""] + (open('|ruby bin/apiary help', 'r') {|f| f.readlines}
+            .map {|l| /^ +apiary /.match(l)?l:nil}
+            .map {|l| /^ *apiary help/.match(l)?nil:l}
+            .compact
+            .map {|l| /^ *apiary ([^ ]*)/.match(l)[1] + " " }
+          )
+  ).each do |cmd|
+
+    it "includes help #{cmd}in README.md" do
+      helptext = open("|ruby bin/apiary help #{cmd}") {|f| f.read}
+
+      expect(helptext).to include("apiary #{cmd.strip}")
+      expect(READMETEXT).to include("apiary #{cmd.strip}")
+      expect(READMETEXT).to include(helptext)
+
+    end
+  end
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apiaryio
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2015-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: 1.6.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: 1.6.4
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement