feat: Implement aegir-docs

README.md

@@ -225,6 +225,19 @@ $ aegir-relase --first
 You can skip all changelog generation and the github release by passing
 in `--no-changelog`.
 
+If you want documentation generation you can pass `--docs` to the release task to build documentation and publish it to the `gh-pages` branch.
+
+### Documentation
+
+You can use `aegir-docs` to generate documentation. This uses [documentation.js](http://documentation.js.org/) with the theme [https://github.com/dignifiedquire/clean-documentation-theme].
+
+To publish the documentation automatically to the `gh-pages` branch you can run
+
+```bash
+$ aegir-docs --publish
+```
+
+
 ## Other Notes
 
 There is a badge.

bin/docs

@@ -0,0 +1,15 @@
+#! /usr/bin/env node
+
+'use strict'
+
+const gulp = require('gulp')
+const args = require('args-parser')(process.argv)
+
+require('../src/gulp-log')(gulp)
+require('../gulp')(gulp, ['docs'])
+
+if (args.publish) {
+  gulp.start('docs:publish')
+} else {
+  gulp.start('docs:build')
+}

config/eslintrc.yml

@@ -30,3 +30,4 @@ rules:
   require-yield: 2
   max-nested-callbacks: [2, 4]
   max-depth: [2, 4]
+  valid-jsdoc: [2, {'requireParamDescription': false, 'requireReturnDescription': false}]

gulp/index.js

@@ -12,7 +12,8 @@ module.exports = (gulp, tasks) => {
       'release',
       'coverage',
       'lint',
-      'default'
+      'default',
+      'docs'
     ]
   }
 

package.json

@@ -11,7 +11,8 @@
     "aegir-build": "bin/build",
     "aegir-test": "bin/test",
     "aegir-release": "bin/release",
-    "aegir-coverage": "bin/coverage"
+    "aegir-coverage": "bin/coverage",
+    "aegir-docs": "bin/docs"
   },
   "scripts": {
     "lint": "bin/lint",
@@ -28,16 +29,19 @@
   "dependencies": {
     "args-parser": "^1.0.2",
     "chalk": "^1.1.3",
+    "clean-documentation-theme": "^0.4.2",
     "conventional-github-releaser": "^1.1.3",
-    "coveralls": "^2.11.14",
+    "coveralls": "^2.11.15",
     "detect-node": "^2.0.3",
-    "eslint": "^3.9.1",
+    "eslint": "^3.11.1",
     "eslint-config-standard": "^6.2.1",
-    "eslint-plugin-promise": "^3.3.0",
+    "eslint-plugin-promise": "^3.4.0",
     "eslint-plugin-standard": "^2.0.1",
+    "gh-pages": "^0.12.0",
     "gulp": "^3.9.1",
-    "gulp-bump": "^2.5.0",
+    "gulp-bump": "^2.5.1",
     "gulp-conventional-changelog": "^1.1.0",
+    "gulp-documentation": "^3.1.0",
     "gulp-eslint": "^3.0.1",
     "gulp-filter": "^4.0.0",
     "gulp-git": "^1.12.0",
@@ -53,26 +57,27 @@
     "karma": "^1.3.0",
     "karma-chrome-launcher": "^2.0.0",
     "karma-firefox-launcher": "^1.0.0",
-    "karma-mocha": "^1.2.0",
+    "karma-mocha": "^1.3.0",
     "karma-mocha-own-reporter": "^1.1.2",
     "karma-sauce-launcher": "^1.1.0",
     "karma-sourcemap-loader": "^0.3.7",
     "karma-webpack": "^1.8.0",
     "lodash.camelcase": "^4.3.0",
     "lodash.includes": "^4.3.0",
     "lodash.upperfirst": "^4.3.1",
-    "mocha": "^3.1.2",
-    "pretty-hrtime": "^1.0.2",
+    "mocha": "^3.2.0",
+    "path-exists": "^3.0.0",
+    "pretty-hrtime": "^1.0.3",
     "pump": "^1.0.1",
     "rimraf": "^2.5.4",
     "run-sequence": "^1.2.2",
     "semver": "^5.3.0",
-    "signal-exit": "^3.0.1",
-    "stream-http": "^2.4.1",
+    "signal-exit": "^3.0.2",
+    "stream-http": "^2.5.0",
     "transform-loader": "^0.2.3",
     "uglify-js": "github:mishoo/UglifyJS2#harmony",
     "webpack": "^2.1.0-beta.26",
-    "webpack-merge": "^1.0.1"
+    "webpack-merge": "^1.0.2"
   },
   "repository": {
     "type": "git",
@@ -89,4 +94,4 @@
     "greenkeeperio-bot <support@greenkeeper.io>",
     "npmcdn-to-unpkg-bot <npmcdn-to-unpkg-bot@users.noreply.github.com>"
   ]
-}
+}

tasks/clean.js

@@ -2,4 +2,5 @@
 
 module.exports = (gulp) => {
   require('./clean/browser')(gulp)
+  require('./clean/docs')(gulp)
 }

tasks/clean/docs.js

@@ -0,0 +1,9 @@
+'use strict'
+
+module.exports = (gulp) => {
+  gulp.task('clean:docs', (done) => {
+    const rimraf = require('rimraf')
+
+    rimraf('./docs', done)
+  })
+}

tasks/docs.js

@@ -0,0 +1,7 @@
+'use strict'
+
+module.exports = (gulp) => {
+  require('./clean')(gulp)
+  require('./docs/build')(gulp)
+  require('./docs/publish')(gulp)
+}

tasks/docs/build.js

@@ -0,0 +1,34 @@
+'use strict'
+
+const pump = require('pump')
+const join = require('path').join
+const docs = require('gulp-documentation')
+const exists = require('path-exists').sync
+
+const pkg = require('../../config/user').pkg
+
+module.exports = (gulp) => {
+  gulp.task('docs:build', ['clean:docs'], (cb) => {
+    const options = {
+      github: true
+    }
+
+    const configFile = join(process.cwd(), 'documentation.yml')
+    if (exists(configFile)) {
+      options.config = configFile
+    }
+
+    pump(
+      gulp.src([
+        './src/**/*.js'
+      ]),
+      docs('html', options, {
+        theme: require.resolve('clean-documentation-theme'),
+        version: pkg.version,
+        name: pkg.name
+      }),
+      gulp.dest('./docs'),
+      cb
+    )
+  })
+}

tasks/docs/publish.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const join = require('path').join
+const ghPages = require('gh-pages')
+const util = require('gulp-util')
+
+module.exports = (gulp) => {
+  gulp.task('docs:publish', ['docs:build'], (cb) => {
+    ghPages.publish(join(process.cwd(), 'docs'), {
+      message: 'docs: auto build',
+      logger (msg) {
+        util.log(`'${util.colors.cyan('docs:publish')}' ${msg}`)
+      }
+    }, cb)
+  })
+}

tasks/release/docs.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const includes = require('lodash.includes')
+const runSequence = require('run-sequence')
+
+module.exports = (gulp) => {
+  const util = require('gulp-util')
+
+  gulp.task('release:docs', (cb) => {
+    if (includes(util.env._, 'docs')) {
+      runSequence.use(gulp)('docs:publish', cb)
+      return
+    }
+
+    cb()
+  })
+}