Documenting Sass with SassDoc

November 28, 2014, 9:12 pm
Author: James Griffiths

So you've been working with Sass for some time now; creating functions and mixins for use in your team projects but now you've got a new developer picking up where you've left off - how to get them up to speed on working with the code you crafted?

Enter SassDoc...

Installing SassDoc

If you have Node installed on your system then installing SassDoc is as simple as firing up the command line and running the following command:

npm install sassdoc -g

Now, assuming there were no errors with your installation, you can start marking up your Sass files with SassDoc compliant syntax.

Documenting your SaSS

If you're familiar with YUIDoc then you'll have no problems working with SassDoc as the selector syntax is very similar (albeit with 3 forward slashes for comment delimiters)  - for example:

///
///
/// Defines and implements a background gradient value for DOM elements
///
/// @access public
/// @author Bonzo Dog Doo-dah band
/// @param {String} $from    The hexadecimal value to start the gradient from
/// @param {String} $to      The hexadecimal value to end the gradient at
/// @example
/// backgroundGradient(#000000, #ffffff);
/// @since 1.0
////

This makes working with Sass commenting so much easier for developer's who have experience of the aforementioned YUIDoc or JSDoc and, unlike other documenting tools such as styledocco, detailed documentation is easy to generate thanks to the wide range of annotations available:

With such a wide range of documentation options available other team members who pick up your Sass files should have no problems understanding what different sections of the files are designed to do when reading the published comments.

Publishing

Finally, when it comes to generating your documentation you have a number of options available - use SassDoc from the command line, parse with Node or run SassDoc as part of a workflow automation process in a tool such as Grunt or Gulp.

To trigger SassDoc from the command line simply run the following:

sassdoc   [options]

Where is your source directory containing all the Sass files you want to publish, is your target folder where documentation will be published to and [options] allows you to specify certain flags that you want to be triggered, for example:

sassdoc ./sass-files ./css-documentation -v

// -v = Verbose mode - display detailed information
sassdoc ./sass-files ./css-documentation -c ./config.yml

// -c = Path to configuration file - JSON or YML format

Whether you're using plug-ins for workflow automation tools such as Grunt and Gulp or are simply running SassDoc from the command line you should, assuming your paths are specified correctly, see HTML documentation being generated akin to the following:

Sassdoc generated documentation

Isn't that just gorgeous?

When was the last time you came across documented code that looked that good?

A beautifully styled and well structured interface makes the published Sass documentation a pleasure to use and interact with rather than some dry, dull looking block of content that many other code documentation tools often produce.

Sassdoc generated documentation

Thanks to the incredibly easy to use SassDoc team members, new and existing, can now work with your Sass files and gain a much better overview and detailed understanding of what different sections of the code are designed to do. Less time taken to research the code to try and make head and tail of what's been written and more time spent being productive  - what development team could argue with those benefits? 

If you haven't tried SassDoc already give it a whirl, it's definitely one of the more impressive Sass tools out there right now.

Categories

« Return to Posts

Post a comment

All comments are welcome and the rules are simple - be nice and do NOT engage in trolling, spamming, abusiveness or illegal behaviour. If you fail to observe these rules you will be permanently banned from being able to comment.