Close GH-801: API Doc Generation 2. Fixes #747

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 dist/*
 build/files/*
+docs/api/*
 dev.html
 projects
 .zenflow-log

Gruntfile.js

@@ -20,6 +20,13 @@ module.exports = function(grunt) {
   };
   version.majorMinor = version.major + '.' + version.minor;
 
+  // loading predefined source order from source-loader.js
+  // trust me, this is the easist way to do it so far
+  /*jshint undef:false, evil:true */
+  var blockSourceLoading = true;
+  var sourceFiles; // Needed to satisfy jshint
+  eval(grunt.file.read('./build/source-loader.js'));
+
   // Project configuration.
   grunt.initConfig({
     pkg: pkg,
@@ -131,6 +138,15 @@ module.exports = function(grunt) {
         configFile: 'test/karma.conf.js',
         autoWatch: false
       }
+    },
+    vjsdocs: {
+      all: {
+        src: sourceFiles,
+        dest: 'docs/api',
+        options: {
+          baseURL: 'https://github.com/videojs/video.js/blob/master/'
+        }
+      }
     }
   });
 
@@ -144,6 +160,10 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-s3');
   grunt.loadNpmTasks('contribflow');
   grunt.loadNpmTasks('grunt-karma');
+  grunt.loadNpmTasks('videojs-doc-generator');
+
+  // grunt.loadTasks('./docs/tasks/');
+  // grunt.loadTasks('../videojs-doc-generator/tasks/');
 
   // Default task.
   grunt.registerTask('default', ['jshint', 'less', 'build', 'minify', 'dist']);
@@ -155,14 +175,6 @@ module.exports = function(grunt) {
       gzip = require('zlib').gzip;
 
   grunt.registerMultiTask('build', 'Building Source', function(){
-    /*jshint undef:false, evil:true */
-
-    // Loading predefined source order from source-loader.js
-    // Trust me, this is the easist way to do it so far.
-    var blockSourceLoading = true;
-    var sourceFiles; // Needed to satisfy jshint
-    eval(grunt.file.read('./build/source-loader.js'));
-
     // Fix windows file path delimiter issue
     var i = sourceFiles.length;
     while (i--) {
@@ -307,4 +319,5 @@ module.exports = function(grunt) {
       done();
     });
   });
+
 };

docs/guides/api.md

@@ -0,0 +1,44 @@
+API
+===
+
+The Video.js API allows you to interact with the video through JavaScript, whether the browser is playing the video through HTML5 video, Flash, or any other supported playback technologies.
+
+Referencing the Player
+----------------------
+To use the API functions, you need access to the player object. Luckily this is easy to get. You just need to make sure your video tag has an ID. The example embed code has an ID of "example\_video_1". If you have multiple videos on one page, make sure every video tag has a unique ID.
+
+```js
+var myPlayer = videojs('example_video_1');
+```
+
+(If the player hasn't been initialized yet via the data-setup attribute or another method, this will also initialize the player.)
+
+Wait Until the Player is Ready
+------------------------------
+The time it takes Video.js to set up the video and API will vary depending on the playback technology being used (HTML5 will often be much faster to load than Flash). For that reason we want to use the player's 'ready' function to trigger any code that requires the player's API.
+
+```javascript
+videojs("example_video_1").ready(function(){
+  var myPlayer = this;
+
+  // EXAMPLE: Start playing the video.
+  myPlayer.play();
+
+});
+```
+
+API Methods
+-----------
+Now that you have access to a ready player, you can control the video, get values, or respond to video events. The Video.js API function names follow the [HTML5 media API](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html). The main difference is that getter/setter functions are used for video properties.
+
+```js
+
+// setting a property on a bare HTML5 video element
+myVideoElement.currentTime = "120";
+
+// setting a property on a Video.js player
+myPlayer.currentTime(120);
+
+```
+
+The full list of player API methods and events can be found in the [player API docs](../api/player.md).