docs(): improve documentation

README.md

@@ -5,7 +5,7 @@ _sia_ is a documentation generator built on [dgeni] that uses [Angular Material]
 ## Usage
 
 ```sh
-npm install sia
+npm install sia --save-dev
 ```
 
 ```js
@@ -17,21 +17,40 @@ require('sia')(gulp, {
   basePath: __dirname,
   moduleTitle: 'My Module',
   modulePrefix: 'myModule',
+  ngVersion: '1.4.6',
   moduleJs: ['../my-module.js'],
   moduleCss: ['../my-module.css'],
-  version: pkg.version,
-  ngVersion: '1.4.6',
   repositoryUrl: pkg.repository && pkg.repository.url.replace(/^git/, 'https').replace(/(\.git)?\/?$/,'')
 });
 ```
 
+Generate docs:
+
 ```sh
 gulp docs
 ```
 
-#### Content
+Serve docs with local webserver:
+
+```sh
+gulp docs:serve
+```
+
+### Options
+
+- **basePath** `string` - Base path where `src` and `docs` folders are located.
+- **moduleTitle** `string` - Title displayed in docs.
+- **modulePrefix** `string` - Module prefix used when determining module ids from folder structure.
+- **ngVersion** `string`  - AngularJS version to load.
+  (*angular*, *angular-animate*, *angular-route*, *angular-aria*, and *angular-messages* are automatically loaded)
+- **moduleJs** `Array` - JavaScript files to load.
+- **moduleCss** `Array` - CSS files to load.
+- repositoryUrl `string` - Repository base URL.
+- debug `boolean` - Debug mode. Default `false`.
 
-Markdown files in the `docs` folder that have `@ngdoc content` are included in the generated docs. Create the
+### Content
+
+Markdown files in `{basePath}/docs` that have `@ngdoc content` are included in the generated docs. Create the
 documentation homepage at `docs/index.md`:
 
 ```html
@@ -42,12 +61,14 @@ documentation homepage at `docs/index.md`:
 ...
 ```
 
-Markdown files with `@area nav` will be displayed in the navigation bar.
+To display a file in the docs sidenav use `@area nav`.
+
+### Components
 
-#### Components
+Components in `{basePath}/src}` that have `@ngdoc service`, `@ngdoc directive`, or `@ngdoc filter` are included in the
+docs if they belong to a documented module.
 
-Documentation is only generated for components whose modules are also documented.  For example, if you have a directive
-belonging to `myApp.components.accordion` you must also add an `ngDoc` for that module:
+For example:
 
 ```js
 /**

package.json

@@ -24,6 +24,7 @@
     "dgeni": "^0.4.1",
     "dgeni-packages": "^0.10.19",
     "gulp-concat": "^2.6.0",
+    "gulp-help": "^1.6.1",
     "gulp-if": "^1.2.5",
     "gulp-ng-annotate": "^1.1.0",
     "gulp-ng-constant": "^1.1.0",

src/index.js

@@ -18,9 +18,25 @@ var util = require('./util');
 
 var appDir = path.join(__dirname, 'app');
 
+/**
+ * Adds gulp documentation tasks.
+ * @param {object} gulp
+ * @param {object} config
+ * @param {string} config.basePath Base path where `src` and `docs` folders are located
+ * @param {string} config.moduleTitle Title displayed in docs.
+ * @param {string} config.modulePrefix Module prefix (used when determining module ids from folder structure)
+ * @param {string} config.ngVersion AngularJS version to load
+ * (*angular*, *angular-animate*, *angular-route*, *angular-aria*, and *angular-messages* are automatically loaded)
+ * @param {Array}  config.moduleJs Module JavaScript files
+ * @param {Array}  config.moduleCss Module CSS files
+ * @param {string} [config.repositoryUrl] Repository base URL
+ * @param {boolean} [config.debug=false] Debug mode
+ */
 module.exports = function (gulp, config) {
 
-  gulp.task('docs', function (cb) {
+  gulp = require('gulp-help')(gulp);
+
+  gulp.task('docs', 'Generates docs', function (cb) {
     runSequence('docs:clean', [
       'docs:index',
       'docs:dgeni',
@@ -32,15 +48,15 @@ module.exports = function (gulp, config) {
     ], cb);
   });
 
-  gulp.task('docs:clean', function () {
+  gulp.task('docs:clean', false, function () {
     return del('dist/docs');
   });
 
   // Parses ngDocs
-  gulp.task('docs:dgeni', function() {
+  gulp.task('docs:dgeni', false, function() {
     var dgeniPackage = require('./dgeni-package')
       .config(function(log, readFilesProcessor) {
-        log.level = config.dev ? 'info' : 'error';
+        log.level = config.debug ? 'info' : 'error';
         readFilesProcessor.basePath = config.basePath;
       })
       .config(function (componentDataProcessor) {
@@ -51,7 +67,7 @@ module.exports = function (gulp, config) {
   });
 
   // Copies app files
-  gulp.task('docs:app', function() {
+  gulp.task('docs:app', false, function() {
     return gulp.src([
       appDir + '/**/*',
       '!' + appDir + '/partials/**/*.html',
@@ -61,7 +77,7 @@ module.exports = function (gulp, config) {
   });
 
   // Generates AngularJS config constants
-  gulp.task('docs:config', function () {
+  gulp.task('docs:config', false, function () {
     return ngConstant({
       name: 'docsApp.config-data',
       constants: {CONFIG: config},
@@ -72,23 +88,23 @@ module.exports = function (gulp, config) {
   });
 
   // Concatenates and uglifies JS
-  gulp.task('docs:js', ['docs:app', 'docs:config', 'docs:html2js', 'docs:dgeni'], function() {
+  gulp.task('docs:js', false, ['docs:app', 'docs:config', 'docs:html2js', 'docs:dgeni'], function() {
     return gulp.src('dist/docs/js/**/*.js')
       .pipe(ngAnnotate())
       .pipe(concat('docs.js'))
-      .pipe(gulpif(!config.dev, uglify()))
+      .pipe(gulpif(!config.debug, uglify()))
       .pipe(gulp.dest('dist/docs'));
   });
 
   // Concatenates CSS
-  gulp.task('docs:css', ['docs:app'], function() {
+  gulp.task('docs:css', false, ['docs:app'], function() {
     return gulp.src(appDir + '/css/**/*.css')
       .pipe(concat('docs.css'))
       .pipe(gulp.dest('dist/docs'));
   });
 
   // Converts HTML to JS
-  gulp.task('docs:html2js', function() {
+  gulp.task('docs:html2js', false, function() {
     return gulp.src(appDir + '/partials/**/*.html')
       .pipe(ngHtml2js({
         moduleName: 'docsApp.templates',
@@ -99,14 +115,14 @@ module.exports = function (gulp, config) {
   });
 
   // Compiles index template
-  gulp.task('docs:index', function() {
+  gulp.task('docs:index', false, function() {
     return gulp.src(appDir + '/index.html')
       .pipe(template({config: config}))
       .pipe(gulp.dest('dist/docs'));
   });
 
   // Generates demo data
-  gulp.task('docs:demos:data', function() {
+  gulp.task('docs:demos:data', false, function() {
     return gulp.src('src/**/demo*/**/*')
       .pipe(util.parseDemoFiles(config.modulePrefix))
       .pipe(ngConstant({name: 'docsApp.demo-data'}))
@@ -115,20 +131,20 @@ module.exports = function (gulp, config) {
   });
 
   // Copies demo files to `dist/docs/demo-partials` and prefixes CSS with demo ID as parent class.
-  gulp.task('docs:demos:copy', function() {
+  gulp.task('docs:demos:copy', false, function() {
     return gulp.src('src/**/demo*/**/*')
       .pipe(gulpif(/.css$/, util.prefixDemoCss()))
       .pipe(gulp.dest('dist/docs/demo-partials'));
   });
 
   // Concatenates demo scripts
-  gulp.task('docs:demos:scripts', ['docs:demos:copy'], function() {
+  gulp.task('docs:demos:scripts', false, ['docs:demos:copy'], function() {
     return gulp.src('dist/docs/demo-partials/**/*.js')
       .pipe(concat('docs-demo-scripts.js'))
       .pipe(gulp.dest('dist/docs'));
   });
 
-  gulp.task('docs:serve', function() {
+  gulp.task('docs:serve', 'Serves docs', function() {
     var port = args.port || 8000;
     gulp.src('dist')
       .pipe(server({