Kaynağa Gözat

Add gulp task for building docs.

Maciej Gołaszewski 10 yıl önce
ebeveyn
işleme
0fd0a78897

+ 2 - 1
.gitignore

@@ -10,4 +10,5 @@
 node_modules/**
 build/**
 coverage/**
-dist/**
+dist/**
+out/jsdoc

+ 8 - 2
dev/tasks/build/tasks.js

@@ -132,9 +132,11 @@ module.exports = ( config ) => {
 		 * The main build task which is capable of copying, watching, processing and writing all files
 		 * to the `dist/` directory.
 		 *
+		 * @param {Object} buildOptions
+		 * @param {String} buildOptions.formats
 		 * @returns {Stream}
 		 */
-		build() {
+		build( buildOptions ) {
 			//
 			// NOTE: Error handling in streams is hard.
 			//
@@ -166,7 +168,7 @@ module.exports = ( config ) => {
 			//
 			// PS. The assumption is that all errors thrown somewhere inside conversionStream are forwarded to conversionStream.
 			// Multipipe and gulp-mirror seem to work this way, so we get a single error emitter.
-			const formats = options.formats.split( ',' );
+			const formats = ( buildOptions.formats || options.formats ).split( ',' );
 			const codeStream = tasks.src.all( options.watch )
 				.pipe(
 					utils.noop( ( file ) => {
@@ -230,5 +232,9 @@ module.exports = ( config ) => {
 
 	gulp.task( 'build', [ 'build:clean' ], tasks.build );
 
+	gulp.task( 'build-esnext', () => {
+		return tasks.build( { formats: 'esnext' } );
+	} );
+
 	return tasks;
 };

+ 23 - 0
dev/tasks/jsdoc/conf.json

@@ -0,0 +1,23 @@
+{
+	"opts": {
+		"encoding": "utf8",
+		"destination": "out/jsdoc",
+		"recurse": true,
+		"access": "all"
+	},
+	"plugins": [
+		"node_modules/jsdoc/plugins/markdown",
+		"dev/tasks/jsdoc/plugins/export-es6-class"
+	],
+	"source": {
+		"include": [
+			"dist/esnext"
+		],
+		"exclude": [
+			"dist/esnext/test",
+			"dist/esnext/ckeditor5/core/lib"
+		],
+		"includePattern": ".+\\.js(doc)?$",
+		"excludePattern": "(^|\\/|\\\\)_"
+	}
+}

+ 4 - 3
conf.json → dev/tasks/jsdoc/jsdoc.json

@@ -6,15 +6,16 @@
 		"access": "all"
 	},
 	"plugins": [
-		"plugins/markdown",
-		"dev/jsdoc/plugins/export-es6-class"
+		"node_modules/jsdoc/plugins/markdown",
+		"dev/tasks/jsdoc/plugins/comment-fixer"
 	],
 	"source": {
 		"include": [
 			"dist/esnext"
 		],
 		"exclude": [
-			"dist/esnext/test"
+			"dist/esnext/test",
+			"dist/esnext/ckeditor5/core/lib"
 		],
 		"includePattern": ".+\\.js(doc)?$",
 		"excludePattern": "(^|\\/|\\\\)_"

+ 7 - 1
dev/jsdoc/plugins/export-es6-class.js → dev/tasks/jsdoc/plugins/comment-fixer.js

@@ -4,7 +4,6 @@ module.exports = {
 	handlers: {
 		/**
 		 * @see http://usejsdoc.org/about-plugins.html#event-beforeparse
-		 * @see https://github.com/jsdoc3/jsdoc/issues/1137
 		 * @param evt
 		 */
 		beforeParse: function( evt ) {
@@ -13,12 +12,19 @@ module.exports = {
 			let className;
 			let foundClassName = /export default class ([A-Za-z]+)/.exec( evt.source );
 
+			// Fix for {@link https://github.com/jsdoc3/jsdoc/issues/1137}. Export default class is not parsed by jsdoc 3.4.
 			if ( foundClassName ) {
 				className = foundClassName[ 1 ];
 				evt.source =
 					evt.source.replace( 'export default class', 'class' ) +
 					'\nexport default ' + className + ';\n';
 			}
+
+			// TODO: jsdoc fail to parse method with expanded argument list
+			evt.source = evt.source.replace( '...}', '}' );
+
+			// Make code in comments indented with one tab so it will not be shifted.
+			evt.source = evt.source.replace( /\*\t\t/g, '*\t' );
 		}
 	}
 };

+ 16 - 0
dev/tasks/jsdoc/tasks.js

@@ -0,0 +1,16 @@
+/* jshint node: true, esnext: true */
+
+'use strict';
+
+const gulp = require( 'gulp' );
+const jsdoc = require( 'gulp-jsdoc3' );
+
+module.exports = () => {
+	gulp.task( 'docs', [ 'build-esnext' ], function( cb ) {
+		let config = require( './jsdoc.json' );
+
+		// Add readme to output
+		gulp.src( [ 'README.md' ], { read: false } )
+			.pipe( jsdoc( config, cb ) );
+	} );
+};

+ 1 - 0
gulpfile.js

@@ -18,6 +18,7 @@ const config = {
 require( './dev/tasks/build/tasks' )( config );
 require( './dev/tasks/dev/tasks' )( config );
 require( './dev/tasks/lint/tasks' )( config );
+require( './dev/tasks/jsdoc/tasks' )( config );
 
 gulp.task( 'default', [ 'build' ] );
 gulp.task( 'pre-commit', [ 'lint-staged' ] );

+ 1 - 0
package.json

@@ -31,6 +31,7 @@
     "gulp-babel": "^6.1.0",
     "gulp-filter": "^3.0.1",
     "gulp-jscs": "^3.0.2",
+    "gulp-jsdoc3": "^0.2.0",
     "gulp-jshint": "^2.0.0",
     "gulp-mirror": "^1",
     "gulp-rename": "^1.2.2",