Introduction
Starting from version 2.0
and higher SassDoc is able to integrate directly in
your Gulp pipelines without any plugin. In such the gulp-sassdoc plugin has been deprecated.
If you haven’t used Gulp before, be sure to check out the Getting started guide, as it explains how to create a Gulpfile as well as install and use Gulp plugins.
Examples
Bare minimum example, using defaults or .sassdocrc
npm install --save-dev gulp sassdoc
var gulp = require('gulp');
var sassdoc = require('sassdoc');
gulp.task('sassdoc', function () {
return gulp.src('path/to/source/**/*.scss')
.pipe(sassdoc());
});
Example with some options passed in
npm install --save-dev gulp sassdoc
var gulp = require('gulp');
var sassdoc = require('sassdoc');
gulp.task('sassdoc', function () {
var options = {
dest: 'docs',
verbose: true,
display: {
access: ['public', 'private'],
alias: true,
watermark: true,
},
groups: {
'undefined': 'Ungrouped',
foo: 'Foo group',
bar: 'Bar group',
},
basePath: 'https://github.com/SassDoc/sassdoc',
};
return gulp.src('path/to/source/**/*.scss')
.pipe(sassdoc(options));
});
Example adding support for Sass (indented syntax) files
npm install --save-dev gulp sass-convert sassdoc
var gulp = require('gulp');
var converter = require('sass-convert');
var sassdoc = require('sassdoc');
gulp.task('sassdoc', function () {
return gulp.src('path/to/source/**/*.+(sass|scss)')
.pipe(converter({
from: 'sass',
to: 'scss',
}))
.pipe(sassdoc());
});
Example of a Sassy workflow
npm install --save-dev gulp sassdoc gulp-sass
var gulp = require('gulp');
var sassdoc = require('sassdoc');
var sass = require('gulp-sass');
gulp.task('styles', function () {
return gulp.src('path/to/source/**/*.scss')
.pipe(sassdoc())
.pipe(sass())
.pipe(gulp.dest('path/to/styles'));
});
Notes on SassDoc’s stream API
Example of a non Gulp pipeline
SassDoc Stream API is not tight to Gulp, its only requirement is expecting Vinyl files passed trough. The vinyl-source-stream module might comes in handy.
npm install --save-dev vinyl-source-stream sassdoc
var fs = require('fs');
var source = require('vinyl-source-stream');
var sassdoc = require('sassdoc');
fs.createReadStream('./file.scss')
.pipe(source('./file.scss'))
.pipe(sassdoc());
End event
Note: the end
event emitted by SassDoc's stream refers to the end of
the parsing phase. If you want to await for the full documentation process to
end, SassDoc is attaching a promise. This might be interesting if you run a
sequence of tasks.
var gulp = require('gulp');
var sassdoc = require('sassdoc');
gulp.task('sassdoc', function () {
var stream = sassdoc();
gulp.src('path/to/source/**/*.scss')
.pipe(stream)
.on('end', function () {
console.log('End of parsing phase');
});
return stream.promise.then(function () {
console.log('End of documentation process');
});
});
Drain event
Caution! On projects with a relatively high number of files, and if SassDoc is the last stream of the pipeline, you might need to release the back pressure and trigger flowing mode, aka "drain". This is imposed by how Streams 2 works.
var gulp = require('gulp');
var sassdoc = require('sassdoc');
gulp.task('sassdoc', function () {
return gulp.src('path/to/source/**/*.scss')
.pipe(sassdoc())
// Either trigger `resume` event.
.resume();
// Or attach a noop `data` event listener.
.on('data', function () {});
});