Sass Reference
Article

SassDoc

By Hugo Giraudel

SassDoc is a documentation tool for Sass. It is to Sass what JSDoc is to JavaScript, PHPDoc to PHP, and so on. SassDoc intends to document Sass APIs, including functions, mixins, variables and placeholders. It it mostly useful for frameworks and libraries.

SassDoc works with annotations, which are basically comments sticking to specific syntax conventions. By gathering all those annotations, it builds a data tree that ends up being handed over to a theme which creates an HTML document to display the documentation.

Setting up SassDoc consists of:

  1. installing it on your environment;
  2. writing SassDoc compliant comments;
  3. running it on your code base.

Not only is SassDoc one of the few documentation systems for Sass, but it also is optimised for Sass code exclusively. Along these lines, it is fully extensible and themable so one can add generated docs anywhere they belong.

Installing SassDoc

SassDoc is a npm module. Thanks to this, it is easy to install and include in any project. For a global install, use the global flag (-g):

npm install sassdoc -g

For a local install, use --save-dev to add SassDoc to your package.json file:

npm install sassdoc --save-dev

Writing Comments

SassDoc annotation system is heavily inspired from JSDoc. Each item (i.e. function, mixin, variable or placeholder) that needs to be documented is directly preceded by a comment block using triple slashes inline comments (///) giving informations about it. Informations are organised using annotations (e.g. @author, @example…).

Here is a simple example:

/// Helper mixin to size elements in a single line.
/// This mixin is essentially a short hand to define
/// both `width` and `height` simultaneously.
///
/// @group shorthand
/// @author Hugo Giraudel
///
/// @param {Length} $width - Element's width
/// @param {Length} $height [$width] - Element's height
/// @output `width` and `height`
///
/// @example scss - Sizing `.foo`
///   .foo {
///     @include size(100%, 3em);
///   }

@mixin size($width, $height: $width) {
  width: $width;
  height: $height;
}

The first lines create the description. Explaining the item purpose, the description has to come before any other annotation.

Then come the annotations, one by one; most of them are inlined, but some of them can live on several lines. For a complete list of all existing annotations, refer to the official site.

Running SassDoc

Once the code is documented with SassDoc compliant comments, it is time to actually run SassDoc to build the documentation. There are several ways to do that: directly from the CLI, or with either Grunt, the Gulp compliant API, Broccoli, or a Node script. Using the former, this is how it might look like in its simplest form:

sassdoc src-folder/

There are a couple of options available; you can define where to put the docs, exclude patterns, a JSON/YML configuration file, a verbose mode, a strict mode and much more.

For a complete list of all existing options, refer to the official site.