Getting Started with SassDoc

SassDoc is to Sass what JSDoc is to JavaScript: a documentation system to build pretty and powerful docs in the blink of an eye.
– SassDoc.com

So your team is using Sass, and everybody is whipping out amazing @mixins, @extends, custom functions, and maximizing use of all those wonderful, built-in Control Directives (@if, @for, @each, @while). Your team has a system in place for introducing new @mixins to other team members so everybody leverages the goodies. While each team understands each project’s Sass nuances and intricacies, there can be gaps in understanding for team members that are added, or even newly hired employees. This is where the often dreaded documentation can come in handy.

Projects like thoughbot’s Bourbon and Bourbon Neat generate and run their documentation site’s on SassDoc.

Install SassDoc

These instructions assume you’re running Grunt, but SassDoc has documentation on other task runners, like Gulp. You could also just install SassDoc globally as a Node package, with:

# Install SassDoc globally
npm install sassdoc -g

And here is how I would do it (again, with Grunt):

npm install --save-dev grunt-sassdoc

Once the plugin is installed in your desired project be sure to add it to your Gruntfile.js.

grunt.loadNpmTasks('grunt-sassdoc');

And you can now run SassDoc with:

grunt sassdoc

Here is an example of a simple configuration for your Gruntfile, but there are plenty of other options to choose from:

// Tip: you're not required to pass every options,
// just set the one you need.
grunt.initConfig({
  sassdoc: {
    default: {
      src: 'path/to/source',
      options: {
        dest: 'path/to/docs',
        display: {
          access: ['public', 'private'],
          alias: true,
          watermark: true,
        }
      },
    },
  },
});

Writing SassDoc Compliant Comments

With SassDoc installed, we’re ready to start writing our Sass documentation and generating our custom site. Here is an example of some SassDoc compliant comments I wrote on a simple mixin:

// ----------------------------------------------------------------------

  // Margin auto

// ----------------------------------------------------------------------

////
/// @author Damon Cook
/// @group wds
////

/// Horizontally center a block element
///
/// @example scss - Basic Usage Sass
///    .center-my-block-thingie {
///        @include margin-auto();
///    }
///
/// @example scss - Basic Usage CSS Output
///    .center-my-block-thingie {
///        margin-left: auto;
///        margin-right: auto;
///    }

@mixin margin-auto {
    margin-left: auto;
    margin-right: auto;
}

Mostly it is just a matter of using three forward slashes to denote your SassDoc comment block, e.g. ///. Next, you’ll want to brush up on all the Annotations SassDoc has available: http://sassdoc.com/annotations/

#proTip: Use @group to Organize Your Entries

Since we include and use Bourbon Neat in our wd_s project starter via Bower, it is possible to generate and output Neat’s already included SassDoc comments in your project’s SassDoc site. Here is what I used in my Gruntfile on a recent project:

sassdoc: {
    default: {
        src: [
            'themes/custom-theme/sass/**/*.scss',
            'bower_components/bourbon/app/assets/stylesheets',
            'bower_components/neat/app/assets/stylesheets'
        ],
        options: {
            dest: './sassdoc/',
            display: {
                access: ['public'],
                watermark: false
            },
            groups: {
                wds: 'WebDevStudios',
                'undefined': 'Bourbon & Neat'
            },
        },
    },
}, 

Then I use the @group annotation to denote internal documentation vs Bourbon’s, like so:

/// @group wds

Which then outputs our SassDoc site to organize entries like so:

It is a bit of a workaround, and I would prefer that Bourbon’s maintainers included an @group bourbon in their SassDoc comments, but for now this works.

SassDoc Themes, and beyond

By default SassDoc comes with a handy theme, but also provides documentation on creating your own.

Hopefully, you’ve considered implementing some Sass documentation in your next project, and now have the tools to do so. Writing the documentation can add some additional overhead, but encourages consistency and increase knowledge sharing within teams.

Also, stay tuned–I’ll be updating this post in coming weeks as we roll out integration of SassDocs into our wd_s starter project.