praxis 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4684312c88071162f3525b9ee7c88c9f9a7587d2
-  data.tar.gz: fcf53c832ebc5f430dc37b9944ccc334b7ec3678
+  metadata.gz: 969f34805663e8986a5ac60e86216c3139324d98
+  data.tar.gz: 8fb76988854889627663ff66874ecb1a8f4549b0
 SHA512:
-  metadata.gz: a600f9e9857b338f87c3dbec975e016a7f3bee940b0a9c590cfc241e7b05e81825877a92a6b49049089ef76ecabcf127ef978d3d545d828b8d7ce197a0b792d8
-  data.tar.gz: 115db171ee75c4569beab2277e4c917bcd768e444e264b769862373936365a54cff1eaa154c21cf7543b59816756e45aafddbc0dd0c95714afdc392f95cae006
+  metadata.gz: 228bc86fd20fef3ad70b282519266378b6f90333e36438923b5a5ed8c416ccacf7d5ac4444bab3d675a2bdd210a3cb89a62090d3ce780d2a5c62cc9c848216d1
+  data.tar.gz: b355e2bd55fe51389ba695d8348303560208d960694f8832d74ebf59942b3e9088cf757c48ae37109b975d6dac238815f15528457c32655c2baa3c3c9b7cf290

data/.ruby-version

@@ -1 +1 @@
-2.1.2
+2.1.5

data/.travis.yml

@@ -1,5 +1,18 @@
 language: ruby
 cache: bundler
 rvm:
-  - "2.1.2"
-script: bundle exec rspec spec
+  - "2.1.5"
+node_js:
+  - "0.10"
+branches:
+  only:
+    - master
+before_install:
+  - cd lib/api_browser
+  - npm install
+  - cd ../..
+script:
+  - bundle exec rspec spec
+  - cd lib/api_browser
+  - npm test
+  - cd ../..

data/CHANGELOG.md

@@ -2,8 +2,60 @@
 
 ## next
 
-## 0.13.0
+## 0.14.0 
+
+* Adds features for customizing and exporting the Doc browser, namely the following changes:
+  1. All doc browser stuff is now centralised under the `praxis:docs` namespace.
+  2. The doc browser requires node.js. (TODO: add this to the docs PR)
+  3. `rake praxis:docs:generate` generates the JSON schema files. `rake praxis:api_docs` is now an alias of this with the idea that `rake praxis:api_docs` will be deprecated.
+  4. `rake praxis:docs:preview` will open a browser window with the doc browser. It will refresh automatically when the design files change as well as when any customisations change.
+  5. `rake praxis:docs:build` will generate a fully built static version of the app in `docs/output`. This can then be put on S3 or GH pages and should work.
+  6. The default app generator will now generate a docs directory with some files to get you started.
+  7. Any `.js` file in the `docs` directory will be included in the doc browser. Angular's dependency injection allows users to override any service or controller as needed.
+  8. The default `docs/styles.scss` simply `@import 'praxis'`. However this means the user can override any of bootstraps variables allowing for easy theme customisation. Rules etc. can now also be overridden.
+  9. Any templates defined in `docs/views` take precedence over those defined in the doc browser. This means the user can easily customise parts of the app, while leaving the rest up to us.
+  10. Any changes to the above customisations will be automatically reloaded on save.
+* First pass at describing (and doc-generating) API global information
+  * Inside a `Praxis::ApiDefinition.define` block one can now specify a few things about the API by using:
+    * info("1.0") `<block>` - Which will apply to a particular version only
+    * info `<block>` - Which will be inherited by any existing API version
+    * The current pieces of information that can be defined in the block are: `name`, `title`, `description` and `basepath`. See [this](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/api.rb) for details
+  * NOTE: This information is output to the JSON files, BUT not used in the doc browser yet.
+* Changed the doc generation and browser to use "ids" instead of "names" for routes and generated files.
+  * Currently, "ids" are generated using dashes instead of double colons (instead of random ids). This closes issue #31.
+* Added the definition and handling of canonical urls for API resources
+  * One can now specify which action URL should be considered as the canonical resource href:
+    * by using `canonical_path <action_name>` at the top of the resource definition class
+    * See the [instances](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/resources/instances.rb) resource definition for an example.
+  * With a canonical href defined, one can then both generate and parse them by using:
+    * `.to_href(<named arguments hash>)  =>  <href String>`
+    * `.parse_href( <href String> )  => < named arguments hash >`. Note: The returned arguments are properly typed-coerced.
+    * These helpers can be accessed from:
+      * the `definition` object in the controller instance (i.e., `self.definition.to_href(id: 1). )
+      * or through the class-level methods in the resource definition (i.e. `MyApiResource.parse_href("/my_resource/1")` )
+* Hooked up rake tasks into the `praxis` binary for convenience. In particular
+  * praxis routes [json]
+  * praxis docs [browser]
+  * praxis console
+* Added `MediaTypeCommon` module, which contains the `identifier`, `description`, and `describe` methods formerly found in `MediaType`. This is now the module used for checking whether a given class should be included in generated documentation, or is valid for use in a `ResponseDefinition`
+* Improved `Praxis::Collection.of` when used with MediaTypes
+  * It will now define an inner `<media_type>::Collection` type that is an `Attributor::Collection` of the MediaType that also will include the `MediaTypeCommon` module.
+  * By default, Praxis will take the identifier of the parent `MediaType` and append a `collection=true` suffix to it.
+* Fixed `ResponseDefinition` Content-Type validation to properly handle parameters (i.e., "application/json;collection=true").
+  * Note: For "index" type actions, this now means Praxis will properly validate any 'collection=true' parameter specified in the `ResponseDefintion` and set by the controller.
+* Deprecated `MediaTypeCollection`. Please define separate classes and attributes for "collection" and "summary" uses.
+* Improved code for stages
+  * `setup!` is no longer called within the `run` default code of a stage
+  * removed unnecessary raise error when substages are empty (while not common it can be possible, and totally valid)
+* Add `Response` to supported classes in `PluginConcern`
+* Fix doc generation to use `ids` for top-level types (rather than names) so they are correctly linkable.
+* Doc Browser: Added support for Markdown rendering of descriptions (for resources, media_types, attributes, etc...)
+* Added test framework for the doc browser. Run the tests with `grunt test` from lib/api_browser.
+* Enhanced the `praxis:docs:preview` rake task with an optional port parameter
+* Fixed praxis:routes rake task to support actions that do not have routes defined
+* Added `:source` to `ActionDefinition` parameter descriptions with the value of either 'url' or 'query' to denote where the parameter is (typically) extracted from. Note: not currently shown in doc browser.
 
+## 0.13.0
 * Added `nodoc!` method to `ActionDefinition`, `ResourceDefinition` to hide actions and resources from the generated documentation.
 * Default HTTP responses:
   * Added descriptions
@@ -24,6 +76,7 @@
   * This is not compatible if it also wants to use the `links` DSL.
 
 
+
 ## 0.11.2
 
 * The Doc Browser will now not change the menu when refreshing.

data/bin/praxis

@@ -2,12 +2,59 @@
 
 require 'bundler'
 
+Bundler.setup :default, :test
+Bundler.require :default, :test
+
+
+if ["routes","docs","console"].include? ARGV[0]
+  require 'rake'
+  require 'praxis'
+  require 'praxis/tasks'
+  
+  case ARGV[0]
+    when "routes"
+      Rake::Task['praxis:routes'].invoke(ARGV[1])
+    when "docs"
+      task_name = case ARGV[1]
+      when nil,'browser'
+        'praxis:docs:preview'
+      when 'generate'
+        'praxis:docs:generate'
+      when 'package'
+        'praxis:docs:build'        
+      end
+#      task_name = ARGV[1] == 'browser' ? 'praxis:doc_browser' : 'praxis:api_docs' 
+      Rake::Task[task_name].invoke
+    when "console"
+      Rake::Task['praxis:console'].invoke
+  end
+  exit 0
+end
+# Thor tasks
 path_to_praxis = File.expand_path(File.dirname(File.dirname(__FILE__)))
 path_to_loader = '%s/tasks/loader.thor' % path_to_praxis
 
 load path_to_loader
 
 class PraxisGenerator < Thor
+  
+  # Include a few fake thor action descriptions (for the rake tasks above) so they can show up in the same usage messages
+  desc "routes [json]", "Prints the route table of the application. Defaults to table format, but can produce json"
+  def routes
+  end
+
+  desc "docs [generate|browser|package]", <<-EOF  
+  Generates API documentation and a Web App to inspect it
+    generate - Generates the JSON docs
+    browser  - (default) Generates JSON docs, and automatically starts a Web app to browse them.
+    package  - Generates JSON docs, and neatly packages all the necessary static files ready for exporting the browsing app.
+  EOF
+  def docs
+  end
+  
+  desc "console", "Open a console to the application, with its environment loaded"
+  def console
+  end
 
   # Simple helper to go get the existing description for the real action
   # Usage must still be provided rather than retrieved (since it is not a 
@@ -33,7 +80,7 @@ class PraxisGenerator < Thor
   def generate(app_name)
     warn "This is a deprecated method.\nTo generate a hello world example, please use:\n  praxis example #{app_name} "
   end
+  
 end
-
-
+    
 PraxisGenerator.start(ARGV)

data/lib/api_browser/Gruntfile.js

@@ -3,13 +3,24 @@ module.exports = function(grunt) {
   require('load-grunt-tasks')(grunt);
 
   // Time how long tasks take. Can help when optimizing build times
-  require('time-grunt')(grunt);
+  try {
+    require('time-grunt')(grunt);
+  } catch(e) {
+
+  }
+
+  var userDocsPath = process.env.USER_DOCS_PATH,
+      buildPath    = userDocsPath + '/output',
+      browserPort  = process.env.DOC_PORT || '9090';
+
+  var cssOutput = {};
+  cssOutput[buildPath + '/css/main.css'] = userDocsPath + '/styles.scss';
 
   grunt.initConfig({
     // web server for development
     connect: {
       options: {
-        port: '9090',
+        port: browserPort,
         hostname: '0.0.0.0'
       },
       livereload: {
@@ -17,6 +28,7 @@ module.exports = function(grunt) {
           livereload: 9091,
           open: true,
           base: [
+            userDocsPath,
             '.tmp',
             '.data',
             'app'
@@ -25,77 +37,38 @@ module.exports = function(grunt) {
       },
       dist: {
         options: {
-          base: ['.data', 'dist']
+          base: ['.data', buildPath]
         }
       }
     },
 
     clean: {
-      dist: {
+      serve: {
         files: [{
           dot: true,
           src: [
-            '.tmp',
-            'dist/*',
-            '!dist/.git*'
+            '.tmp'
           ]
         }]
-      }
-    },
-
-    // Watches files for changes
-    watch: {
-      // Reload stuff when the grunt file changes
-      config: {
-        files: ['Gruntfile.js'],
-        tasks: 'prep',
-        options: {
-          reload: true
-        }
-      },
-
-      // Updates index.html for any file added or removed
-      scripts: {
-        files: ['app/js/**/*.js'],
-        tasks: 'fileblocks:scripts',
-        options: { livereload: 9091 }
-      },
-
-      // Updates index.html for any bower component added or removed
-      bowerComponents: {
-        files: ['app/bower_components/**/*'],
-        tasks: 'wiredep',
-        options: { livereload: 9091 }
       },
-
-      // Rebuild the stylesheets for any SASS file changed
-      sass: {
-        files: [
-          'app/sass/**/*.scss',
-          'app/bower_components/**/*.scss'
-        ],
-        tasks: 'sass',
-        options: { livereload: 9091 }
-      },
-
-      // Watches files that don't need processing
-      other: {
-        files: [
-          'app/css/*.css',
-          "app/index.html",
-          "app/views/**/*.html"
-        ],
+      dist: {
         options: {
-          livereload: 9091
-        }
+          force: true,
+        },
+        files: [{
+          dot: true,
+          src: [
+            '.tmp',
+            buildPath
+          ]
+        }]
       }
     },
-
     // Automatically inject Bower components into the app
     wiredep: {
       app: {
-        src: 'app/index.html',
-        ignorePath: 'app/',
+        src: '.tmp/index.html',
+        ignorePath: /(..\/)?app\//,
         // We do not use bootstrap's JS code, also the SASS styles are included by our style sheet
         exclude: [/bootstrap-sass/]
       }
@@ -104,13 +77,34 @@ module.exports = function(grunt) {
     // Automatically inject the JS files into the app
     fileblocks: {
       options: { removeFiles: true },
-      scripts: {
+      dist: {
+        src: 'app/index.html',
+        dest: '.tmp/index.html',
+        blocks: {
+          scripts: {
+            cwd: 'app',
+            // This ensures app.js comes first so the angular module is declared
+            src: ['js/app.js', 'js/**/*.js']
+          },
+          userscripts: {
+            // cwd: userDocsPath,
+            src: [userDocsPath + '/app.js', userDocsPath + '/**/*.js', '!' + userDocsPath + '/output/**/*.js']
+          }
+        }
+      },
+
+      serve: {
         src: 'app/index.html',
+        dest: '.tmp/index.html',
         blocks: {
           scripts: {
             cwd: 'app',
             // This ensures app.js comes first so the angular module is declared
             src: ['js/app.js', 'js/**/*.js']
+          },
+          userscripts: {
+            cwd: userDocsPath,
+            src: ['app.js', '**/*.js', '!output/**/*.js']
           }
         }
       }
@@ -121,29 +115,28 @@ module.exports = function(grunt) {
       server: {
         options: {
           sourceComments: 'map',
-          sourceMap: 'app/css/main.css.map'
+          sourceMap: __dirname  + '/.tmp/css/main.css.map',
+          includePaths: ['app/sass']
         },
         files: {
-          'app/css/main.css': 'app/sass/main.scss'
+          '.tmp/css/main.css': userDocsPath + '/styles.scss'
         }
       },
       dist: {
         options: {
-          sourceComments: 'none'
+          sourceComments: 'none',
+          includePaths: ['app/sass']
         },
-        files: {
-          'dist/css/main.css': 'app/sass/main.scss'
-        }
+        files: cssOutput
       }
     },
 
     cssmin: {
       dist: {
-        files: {
-          'dist/css/main.css': [
-            'dist/css/main.css'
-          ]
-        }
+        files: [{
+          src: buildPath + '/css/main.css',
+          dest: buildPath + '/css/main.css'
+        }]
       }
     },
 
@@ -152,7 +145,7 @@ module.exports = function(grunt) {
         files: [{
           expand: true,
           cwd: '.tmp/concat/scripts',
-          src: 'scripts.js',
+          src: '*.js',
           dest: '.tmp/concat/scripts'
         }]
       }
@@ -161,8 +154,8 @@ module.exports = function(grunt) {
     filerev: {
       dist: {
         src: [
-          'dist/scripts/*.js',
-          'dist/css/*.css'
+          buildPath + '/scripts/*.js',
+          buildPath + '/css/*.css'
         ]
       }
     },
@@ -179,16 +172,27 @@ module.exports = function(grunt) {
           removeScriptTypeAttributes: true,
           removeStyleLinkTypeAttributes: true
         },
-        module: 'docBrowser',
         bootstrap: function(module, script) {
           return 'angular.module("' + module + '").run(function($templateCache){' + script + '});';
         },
-        usemin: 'dist/scripts/scripts.js'
       },
       dist: {
         cwd: 'app',
         src: 'views/**/*.html',
-        dest: '.tmp/templates.js'
+        dest: '.tmp/templates.js',
+        options: {
+          usemin: buildPath + '/scripts/praxis.js',
+          module: 'PraxisDocBrowser',
+        }
+      },
+      userScripts: {
+        cwd: userDocsPath,
+        src: 'views/**/*.html',
+        dest: '.tmp/usertemplates.js',
+        options: {
+          usemin: buildPath + '/scripts/docs.js',
+          module: 'DocBrowser',
+        }
       }
     },
 
@@ -198,10 +202,25 @@ module.exports = function(grunt) {
           expand: true,
           dot: true,
           cwd: 'app',
-          dest: 'dist',
+          dest: buildPath,
+          src: [
+            '*.{ico,png,txt}'
+          ]
+        }, {
+          expand: true,
+          dot: true,
+          cwd: '.tmp',
+          dest: buildPath,
           src: [
-            '*.{ico,png,txt}',
-            'index.html',
+            'index.html'
+          ]
+        }, {
+          expand: true,
+          dot: true,
+          cwd: userDocsPath,
+          dest: buildPath,
+          src: [
+            'api/**'
           ]
         }]
       }
@@ -211,36 +230,146 @@ module.exports = function(grunt) {
     // concat, minify and revision files. Creates configurations in memory so
     // additional tasks can operate on them
     useminPrepare: {
-      html: 'app/index.html',
+      html: '.tmp/index.html',
       options: {
-        dest: 'dist'
+        dest: buildPath
       }
     },
 
     // Performs rewrites based on rev and the useminPrepare configuration
     usemin: {
-      html: ['dist/{,*/}*.html'],
-      css: ['dist/css/{,*/}*.css'],
+      html: [buildPath + '/index.html'],
+      css: [buildPath + '/css/{,*/}*.css'],
+      options: {
+        assetsDirs: [buildPath]
+      }
+    },
+
+    karma: {
       options: {
-        assetsDirs: ['dist']
+        files: [
+          'node_modules/quick_check/dist/jasmine-quick-check.js',
+          'app/bower_components/jquery/dist/jquery.js',
+          'app/bower_components/angular/angular.js',
+          'app/bower_components/lodash/dist/lodash.compat.js',
+          'app/bower_components/angular-ui-router/release/angular-ui-router.js',
+          'app/bower_components/angular-ui-bootstrap-bower/ui-bootstrap-tpls.js',
+          'app/bower_components/angular-sanitize/angular-sanitize.js',
+          'app/bower_components/angular-mocks/angular-mocks.js',
+          'app/js/app.js', 'app/js/**/*.js', '.tmp/templates.js', '../../spec/api_browser/**/*.js'
+        ],
+        frameworks: ['jasmine'],
+        reporters: ['dots'],
+      },
+      unit: {
+        browsers: ['PhantomJS'],
+        singleRun: true
+      }
+    },
+
+    jshint: {
+      src: ['app/js/**/*.js', '../../spec/api_browser/**/*.js'],
+      options: {
+        bitwise: true,
+        immed: true,
+        newcap: false,
+        noarg: true,
+        noempty: true,
+        nonew: true,
+        trailing: true,
+        boss: true,
+        eqnull: true,
+        expr: true,
+        laxbreak: true,
+        loopfunc: true,
+        sub: true,
+        undef: true,
+        unused: true,
+        browser: true,
+        quotmark: true,
+        indent: 2,
+        jasmine: true,
+        globals: {
+          "angular": false,
+          "app": true,
+          "_": false,
+          "$": false,
+          "jQuery": false,
+          "Showdown": false,
+          "inject": false,
+          "qc": false
+        }
       }
     }
   });
 
-  // Prepares the assets (used by watch:config)
-  grunt.registerTask('prep', [
-      'fileblocks',
-      'wiredep',
-      'sass'
-  ]);
+  grunt.registerTask('runGenerator', function() {
+    var exec = require('child_process').exec;
+    var done = this.async();
+    exec('bundle exec rake praxis:docs:generate', {cwd: userDocsPath + '/../'}, done);
+  });
 
   grunt.registerTask('serve', function(target) {
     if (target === 'dist') {
       return grunt.task.run(['build', 'connect:dist:keepalive']);
     }
 
+    grunt.config.merge({
+      watch: {
+        // Updates index.html for any file added or removed
+        scripts: {
+          files: ['app/js/**/*.js', userDocsPath + '/**/*.js'],
+          tasks: 'fileblocks:serve',
+          options: { livereload: 9091 }
+        },
+
+        // Updates index.html for any bower component added or removed
+        bowerComponents: {
+          files: ['app/bower_components/**/*', userDocsPath + '/bower_components/**/*'],
+          tasks: 'wiredep',
+          options: { livereload: 9091 }
+        },
+
+        // Rebuild the stylesheets for any SASS file changed
+        sass: {
+          files: [
+            'app/sass/**/*.scss',
+            'app/bower_components/**/*.scss',
+            userDocsPath + '/**/*.scss'
+          ],
+          tasks: 'sass',
+          options: { livereload: 9091 }
+        },
+
+        data: {
+          files: [
+            userDocsPath + '/../design/**/*.rb'
+          ],
+          tasks: 'runGenerator',
+          options: { livereload: 9091 }
+        },
+
+        // Watches files that don't need processing
+        other: {
+          files: [
+            'app/css/*.css',
+            "app/index.html",
+            "app/views/**/*.html",
+            userDocsPath + '/views/**/*.html'
+          ],
+          options: {
+            livereload: 9091
+          }
+        }
+      }
+    });
+
+
     grunt.task.run([
-      'prep',
+      'clean:serve',
+      'fileblocks:serve',
+      'wiredep',
+      'sass:server',
       'connect:livereload',
       'watch'
     ]);
@@ -248,7 +377,9 @@ module.exports = function(grunt) {
 
   grunt.registerTask('build', [
     'clean:dist',
-    'prep',
+    'fileblocks:dist',
+    'wiredep',
+    'sass:dist',
     'useminPrepare',
     'ngtemplates',
     'concat',
@@ -260,5 +391,31 @@ module.exports = function(grunt) {
     'usemin'
   ]);
 
+  grunt.registerTask('test', function() {
+    grunt.config.set('watch', {
+      tests: {
+        files: [
+          'app/js/**',
+          '../../spec/api_browser/**'
+        ],
+        tasks: ['jshint:src', 'karma:unit'],
+        options: {
+          atBegin: true
+        }
+      }
+    });
+
+    grunt.task.run([
+      'ngtemplates:dist',
+      'watch:tests'
+    ]);
+  });
+
+  grunt.registerTask('ci', [
+    'ngtemplates:dist',
+    'jshint:src',
+    'karma:unit'
+  ]);
+
   grunt.registerTask("default", ["serve"]);
 };