praxis 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c3c0d0844cabeb646b294a5a91b3c1fff24c848
-  data.tar.gz: edcb41f6707ec368f6a87f0f6273bc6aef558b7b
+  metadata.gz: 1f9e3125f14a1661de76a4f8f5af8749dcc0b2c1
+  data.tar.gz: 5e88bc49232b9ad8dbd7c20b046c49905d14f52c
 SHA512:
-  metadata.gz: afecbf0a00ee48c51eb9c49a1e0867431569e9136ef74a1e852800d143f5f672d276fa5ba80c1339629faf23d518d50067693ddb4f05702925fa4fb2071131f1
-  data.tar.gz: 6348cd21d00aa34085870a0b8af94a4939b31da4d00c962ab4dd49cb316a699a0412082db7e104c18bfb423a731000f04c86422d228be7ecb2ee156573d0afda
+  metadata.gz: 5f0fa85f2dbb7d145f9e56f49aa755a2dc5cf4db65db107f73c468d3b71908e832c404d1b5cc96ac55b6f8a93c9724d7ed43192cb2f5a6fe45b18f8e2ce944b9
+  data.tar.gz: c451e56a47994d560fc3b739bc8f63a08c5f9ffb6ba7136a9b343059bb3c3e5c34c31382e8cdcf2ec2065b00d9d81ff5a7afd7da375d22a582d02eda18469369

data/.gitignore

@@ -9,3 +9,8 @@ _site/
 node_modules/
 *.css.map
 pkg
+
+lib/api_browser/node_modules/
+lib/api_browser/app/bower_components/
+lib/api_browser/.tmp/
+lib/api_browser/bower.json

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## next
 
+## 0.20.0
+
+* You can now add a `bower.json` file to your `docs` folder. Any dependencies
+  you list there will be included in the doc browser.
+* The Plugin API now exposes `Praxis::Plugin#register_doc_browser_plugin(path)`,
+  which allows plugins to register assets that will be included in the doc browser.
+  This is a convenient way to share customizations and optional features amongst
+  different API projects.
+* Fixes an issue where an odd scrollbar would appear in some cases in the doc browser.
+* Fixed a corner-case in doc generation which could omit certain existing MediaTypes
+  (when these existed but there were never referenced in any other part of the app).
+* Added `ApiGeneralInfo` to supported modules a `PluginConcern` can extend.
+* Fixed `MediaType` support for attributor advanced requirements.
+* Doc Browser now exposes an API to register functions that generate code examples.
+  These can be registered with `ExamplesProvider.register` call.
+
 ## 0.19.0
 
 * Handle loading empty `MediaTypeIdentifier` values (to return `nil`)

data/lib/api_browser/Gruntfile.js

@@ -10,12 +10,56 @@ module.exports = function(grunt) {
   }
 
   var userDocsPath = process.env.USER_DOCS_PATH,
+      pluginPaths  = process.env.PLUGIN_PATHS ? process.env.PLUGIN_PATHS.split(':') : [],
       buildPath    = userDocsPath + '/output',
-      browserPort  = process.env.DOC_PORT || '9090';
+      browserPort  = process.env.DOC_PORT || '9090',
+      bowerPaths   = pluginPaths.concat([userDocsPath]).map(function(f) { return f + '/bower.json'; });
 
   var cssOutput = {};
   cssOutput[buildPath + '/css/main.css'] = userDocsPath + '/styles.scss';
 
+  grunt.registerMultiTask('merge_bower', function() {
+    var merge = require('package-merge'),
+        options = this.options({
+          template: {},
+          writePath: './bower.json',
+          install: false
+        }),
+        shouldInstallDevAssets = this.flags.development,
+        files = [],
+        template = options.templatePath ? grunt.file.read(options.templatePath) : JSON.stringify(options.template, null, 2),
+        dependencies = template.dependencies || {},
+        devDependencies = template.devDependencies || {};
+
+    this.files.forEach(function(obj) {
+      files = files.concat(obj.src.filter(function(file) {
+        return grunt.file.exists(file);
+      }));
+    });
+
+    var result = files.reduce(function(combined, file) {
+      grunt.verbose.writelns("Combining " + file);
+      return merge(grunt.file.read(file), combined);
+    }, template);
+
+    grunt.file.write(options.writePath, result);
+
+    if (options.install) {
+      grunt.log.writeln('Installing Bower Dependencies');
+      var exec = require('child_process').exec;
+      var done = this.async();
+      exec('node_modules/.bin/bower install --force-latest' + (shouldInstallDevAssets ? '' : ' --production') + '--config.interactive=false --config.analytics=false', { cwd: '.' }, function(error, result) {
+        if (error) {
+          grunt.log.error('bower install failed with' + error);
+          done(false);
+        } else {
+          grunt.log.ok('Dependencies installed succesfully');
+          done();
+        }
+      });
+    }
+  });
+
   grunt.initConfig({
     // web server for development
     connect: {
@@ -27,12 +71,11 @@ module.exports = function(grunt) {
         options: {
           livereload: 9091,
           open: true,
-          base: [
-            userDocsPath,
+          base: [userDocsPath].concat(pluginPaths).concat([,
             '.tmp',
             '.data',
             'app'
-          ]
+          ])
         }
       },
       dist: {
@@ -83,9 +126,15 @@ module.exports = function(grunt) {
         blocks: {
           scripts: {
             cwd: 'app',
-            // This ensures app.js comes first so the angular module is declared
+            // This ensures app.js comes first so the angular module is declared,
+            // then Praxis core files, then plugin files
             src: ['js/app.js', 'js/**/*.js']
           },
+          pluginscripts: {
+            src: pluginPaths.map(function(path) {
+              return path + '/**/*.js';
+            })
+          },
           userscripts: {
             // cwd: userDocsPath,
             src: [userDocsPath + '/app.js', userDocsPath + '/**/*.js', '!' + userDocsPath + '/output/**/*.js']
@@ -102,6 +151,20 @@ module.exports = function(grunt) {
             // This ensures app.js comes first so the angular module is declared
             src: ['js/app.js', 'js/**/*.js']
           },
+          pluginscripts: {
+            src: pluginPaths.map(function(path) {
+              return path + '/**/*.js';
+            }),
+            templatesFn: {
+              js: function(file) {
+                var pluginPath = pluginPaths.filter(function(path) {
+                  return grunt.file.isMatch(path + '/**/*.js', file);
+                })[0];
+
+                return file.replace(pluginPath + '/', '');
+              }
+            }
+          },
           userscripts: {
             cwd: userDocsPath,
             src: ['app.js', '**/*.js', '!output/**/*.js']
@@ -116,7 +179,7 @@ module.exports = function(grunt) {
         options: {
           sourceComments: 'map',
           sourceMap: __dirname  + '/.tmp/css/main.css.map',
-          includePaths: ['app/sass']
+          includePaths: ['app/sass'].concat(pluginPaths)
         },
         files: {
           '.tmp/css/main.css': userDocsPath + '/styles.scss'
@@ -125,7 +188,7 @@ module.exports = function(grunt) {
       dist: {
         options: {
           sourceComments: 'none',
-          includePaths: ['app/sass']
+          includePaths: ['app/sass'].concat(pluginPaths)
         },
         files: cssOutput
       }
@@ -152,6 +215,9 @@ module.exports = function(grunt) {
               if (object && object.type === 'Identifier' && object.name === 'templateForProvider' && node.callee.property.name === 'register') {
                 return node.arguments[0];
               }
+              if (object && object.type === 'Identifier' && object.name === 'ExamplesProvider' && node.callee.property.name === 'register') {
+                return node.arguments[2];
+              }
             }
           }}]
         }
@@ -192,9 +258,18 @@ module.exports = function(grunt) {
         },
       },
       dist: {
-        cwd: 'app',
-        src: 'views/**/*.html',
-        dest: '.tmp/templates.js',
+        files: [{
+          cwd: 'app',
+          src: 'views/**/*.html',
+          dest: '.tmp/templates.js'
+        }].concat(pluginPaths.map(function (path, i) {
+          return {
+            cwd: path,
+            src: 'views/**/*.html',
+            dest: '.tmp/plugin-templates-' + i + '.js'
+          };
+        })),
+
         options: {
           usemin: buildPath + '/scripts/praxis.js',
           module: 'PraxisDocBrowser',
@@ -239,10 +314,36 @@ module.exports = function(grunt) {
             '!**/*.{js,scss,sass,less,coffee}',
             '!views/**',
             '!**/.*',
-            '!output/**'
-
+            '!output/**',
+            '!bower.json'
           ]
-        }]
+        }].concat(pluginPaths.map(function(path) {
+          return {
+            expand: true,
+            dot: true,
+            cwd: path,
+            dest: buildPath,
+            src: [
+              '**/*',
+              '!**/*.{js,scss,sass,less,coffee}',
+              '!views/**',
+              '!**/.*',
+              '!output/**',
+              '!bower.json'
+            ]
+          };
+        }))
+      }
+    },
+
+    merge_bower: {
+      app: {
+        options: {
+          writePath: 'bower.json',
+          templatePath: 'bower_template.json',
+          install: true
+        },
+        src: bowerPaths
       }
     },
 
@@ -334,7 +435,6 @@ module.exports = function(grunt) {
     if (target === 'dist') {
       return grunt.task.run(['build', 'connect:dist:keepalive']);
     }
-
     grunt.config.merge({
       watch: {
         // Updates index.html for any file added or removed
@@ -346,11 +446,18 @@ module.exports = function(grunt) {
 
         // Updates index.html for any bower component added or removed
         bowerComponents: {
-          files: ['app/bower_components/**/*', userDocsPath + '/bower_components/**/*'],
+          files: ['app/bower_components/**/.bower.json'],
           tasks: 'wiredep',
           options: { livereload: 9091 }
         },
 
+        // watches bower paths to retrigger bower install
+        bower: {
+          files: bowerPaths.concat(['bower_template.json']),
+          tasks: ['merge_bower:app', 'wiredep'],
+          options: { livereload: 9091 }
+        },
+
         // Rebuild the stylesheets for any SASS file changed
         sass: {
           files: [
@@ -385,9 +492,9 @@ module.exports = function(grunt) {
       }
     });
 
-
     grunt.task.run([
       'clean:serve',
+      'merge_bower:app',
       'fileblocks:serve',
       'wiredep',
       'sass:server',
@@ -398,6 +505,7 @@ module.exports = function(grunt) {
 
   grunt.registerTask('build', [
     'clean:dist',
+    'merge_bower:app',
     'fileblocks:dist',
     'wiredep',
     'sass:dist',
@@ -433,6 +541,7 @@ module.exports = function(grunt) {
   });
 
   grunt.registerTask('ci', [
+    'merge_bower:app:development',
     'ngtemplates:dist',
     'jshint:src',
     'karma:unit'

data/lib/api_browser/app/index.html

@@ -6,13 +6,15 @@
   <title ng-bind="subtitle ? title + ' – ' + subtitle : title">API Browser</title>
   <meta name="description" content="">
   <meta name="viewport" content="width=device-width">
+  <!-- build:css({.tmp,app,/}) css/other.css -->
   <!-- bower:css -->
   <!-- endbower -->
+  <!-- endbuild -->
   <link rel="stylesheet" href="css/main.css">
 </head>
 <body>
   <div ui-view=""></div>
-  <!-- build:js({.tmp,app}) scripts/praxis.js -->
+  <!-- build:js({.tmp,app,/}) scripts/praxis.js -->
   <!-- bower:js -->
   <script src="bower_components/jquery/dist/jquery.js"></script>
   <script src="bower_components/angular/angular.js"></script>
@@ -43,6 +45,8 @@
   <script src="js/directives/request_headers.js"></script>
   <script src="js/directives/request_parameters.js"></script>
   <!-- endfileblock -->
+  <!-- fileblock:js pluginscripts -->
+  <!-- endfileblock -->
   <!-- endbuild -->
   <!-- build:js({/,.tmp}) scripts/docs.js -->
   <!-- fileblock:js userscripts -->

data/lib/api_browser/app/js/directives/fixed_if_fits.js

@@ -2,26 +2,37 @@
  * This directive adds the css position fixed if the tabs fit on screen
  */
 
-app.directive('fixedIfFits', function($timeout) {
+app.directive('fixedIfFits', function($timeout, $rootScope) {
   return {
     restrict: 'C',
     link: function(scope, element) {
-      $timeout(function() {
-        var height = _(element.find('.tab-content .tab-pane').get()).map(function(el) {
-          return angular.element(el).height();
-        }).max() + element.offset().top;
-        var mq = window.matchMedia('(min-width: 768px)');
-        if (height < $(window).height() && mq.matches) {
-          var padding = 20;
-          element[0].style.width = (element.width() + padding) + 'px';
-          element[0].style.paddingRight = padding + 'px';
-          var navbarHeight = '' + ($('.navbar').height() || 60) + 'px';
-          element[0].style.height = 'calc(100vh - ' + navbarHeight + ')';
-          element[0].style.paddingBottom = '30px';
-          element[0].style.overflow = 'auto';
-          element[0].style.position = 'fixed';
-        }
-      }, 100);
+      function recalculateLayout() {
+        $timeout(function() {
+          var height = _(element.find('.tab-content .tab-pane').get()).map(function(el) {
+            return angular.element(el).height();
+          }).concat([element[0].scrollHeight]).max() + element.offset().top + element.find('.row:first-of-type').height();
+          var mq = window.matchMedia('(min-width: 768px)');
+          if (height < $(window).height() && mq.matches) {
+            var padding = 20;
+            element[0].style.width = (element.width() + padding) + 'px';
+            element[0].style.paddingRight = padding + 'px';
+            var navbarHeight = '' + ($('.navbar').height() || 60) + 'px';
+            element[0].style.height = 'calc(100vh - ' + navbarHeight + ')';
+            element[0].style.paddingBottom = '30px';
+            element[0].style['overflow-y'] = 'auto';
+            element[0].style.position = 'fixed';
+          } else {
+            element[0].style.width = null;
+            element[0].style.paddingRight = null;
+            element[0].style.height = null;
+            element[0].style.paddingBottom = null;
+            element[0].style['overflow-y'] = null;
+            element[0].style.position = 'static';
+          }
+        }, 100);
+      }
+      recalculateLayout();
+      $rootScope.$on('$stateChangeSuccess', recalculateLayout);
     }
   };
 });

data/lib/api_browser/app/js/directives/highlight.js

@@ -0,0 +1,14 @@
+app.directive('highlight', function() {
+  return {
+    restrict: 'EA',
+    link: function ($scope, element, attrs) {
+      var prism = window.Prism;
+      prism.plugins.autoloader.languages_path = 'https://cdn.jsdelivr.net/prism/1.3.0/components/';
+      element.ready(function() {
+        element.html('<code>' + element.text() + '</code>');
+        element.addClass('language-' + attrs.highlight);
+        prism.highlightElement(element.find('code')[0]);
+      });
+    }
+  };
+});

data/lib/api_browser/app/js/directives/request_examples.js

@@ -0,0 +1,29 @@
+app.directive('requestExamples', function(Examples, $timeout) {
+  return {
+    restrict: 'E',
+    scope: {
+      action: '=',
+      resource: '=',
+      version: '='
+    },
+    template: '<tabset><tab ng-repeat="example in examples" heading="{{example.displayName}}" select="select(example.template)"></tab></tabset>',
+    link: function(scope, element) {
+      scope.examples = Examples.forContext(scope.action, scope.version, scope.resource);
+      var keys = _.keys(scope.examples);
+      if (keys.length === 1) {
+        scope.examples[keys[0]].template.then(function(templateFn) {
+          element.empty().append(templateFn(scope));
+        });
+      } else {
+        scope.select = function(template) {
+          template.then(function(templateFn) {
+            $timeout(function() {
+              element.find('.tab-content:eq(0)>.tab-pane.active:not(.initialized)').append(templateFn(scope)).addClass('initialized');
+              template.then = _.noop;
+            }, 100);
+          });
+        };
+      }
+    }
+  };
+});

data/lib/api_browser/app/js/factories/Documentation.js

@@ -17,6 +17,12 @@ app.factory('Documentation', function($http, $q) {
     versions: function() {
       return versions.then(_.keys);
     },
+    /**
+     * Returns the info for the requested version
+     */
+    info: function(version) {
+      return versions.then(function(v) { return v[version].info; });
+    },
     /**
      * Returns a list of controllers and types, useful for generating navigation
      */

data/lib/api_browser/app/js/factories/Example.js

@@ -0,0 +1,47 @@
+app.provider('Examples', function() {
+  var registry = {};
+
+  this.register = function(key, displayName, handler) {
+    registry[key] = registry[key] || [];
+    registry[key].unshift({
+      key: key,
+      displayName: displayName,
+      handler: handler
+    });
+  };
+
+  this.register('general', 'General', function() {
+    return 'views/examples/general.html';
+  });
+
+  this.$get = function(prepareTemplate, $injector) {
+    return {
+      forContext: function(action, version, resource) {
+        var results = {};
+        for (var key in registry) {
+          for (var i = 0; i < registry[key].length; i++) {
+            var result = $injector.invoke(registry[key][i].handler, this, {
+              $action: action,
+              $version: version,
+              $context: {
+                resource: resource,
+                action: action,
+                version: version
+              }
+            });
+            if (result) {
+              results[key] = {
+                key: key,
+                displayName: registry[key][i].displayName,
+                template: prepareTemplate(result)
+              };
+              break;
+            }
+          }
+        }
+        return results;
+      }
+    };
+  };
+
+});