Hostingheaderbarlogoj
Join InMotion Hosting for $3.49/mo & get a year on Tuts+ FREE (worth $180). Start today.
Advertisement

New Features and a New Look for SassDoc

by
Gift

Want a free year on Tuts+ (worth $180)? Start an InMotion Hosting plan for $3.49/mo.

A couple of weeks ago, I introduced SassDoc at SitePoint while it was still in an early development phase. Since then, we have released no less than one major and two minor versions, respectively: 1.0.0, 1.1.0 and 1.2.0. We've shipped quite a number of features in doing so, so I thought it would be a good idea to introduce them.

If you are not yet familiar with SassDoc, allow me to introduce it. 

What is SassDoc?

SassDoc is to Sass what JSDoc is to JavaScript: a documentation tool based on comments within your work files. The usual scenario is to write comments for your functions, mixins and variables following the documentation guidelines, run SassDoc from the command line and boom. You have yourself generated documentation.

A Better View

When I first introduced SassDoc, the generated documentation was okay I guess. Meanwhile, I really wanted to improve the design because, when all's said and done, if you tell someone you're going to generate beautiful docs for them, you'd better get things right and show them something great!

So I came up with a new dark-based design

This raised quite mitigated opinions to be honest (even I had my reservations). That being said, beauty is in the eye of the beholder, so I kept this one under my hat and came up with another design heavily inspired by the new Google Design.

SassDoc New Design

I hope you like it!

Alongside of this brand new shiny view, we added a lightweight fuzzy search engine based on Fuse. This will make it easier for people with a high number of documented items to quickly reach the one they are looking for without having to scroll forever. Along the same lines, we made the sidebar fixed in the default theme so you can keep an eye on the data structure at all time.

Custom Themes and Templates

In version 1.0.0, we made it possible for you to brand the view by providing a path to a configuration file containing some informations about your project, like the name, the version, the description, the license and so on. The cool thing is, if you happen to have a package.json file (npm project) at root level, we used it so you don't have to duplicate your project's information for SassDoc. So that's pretty nice.

In 1.2 we wanted to push things further. Like waaay further. Our goal was to give you the ability to use your custom themes and your custom templates (with your favourite template engine). Basically, we wanted to hand the data to you so you can do whatever you want with it. Like so:

sassdoc src/folder destination/folder --theme my-awesome-theme

Note: When you set the --theme option of the cli interface, SassDoc will search for a sassdoc-theme-foo package, then ./foo, and finally foo.

Meanwhile, we didn't want to make things too hard on your side so we had our JavaScript genius Valérian Galliat build a theming engine: Themeleon. This is a stand-alone project built for SassDoc but completely independent from it. It's a tiny tiny Node theme engine running with about 100 lines of JavaScript.

You are not obliged to use Themeleon to plug your theme into SassDoc, though it does make the job way easier because it keeps all the technical dirt under the hood. Also, it comes with a mixin (kind of a plugin) for both template engines Swig (themeleon-swig) and Jade (themeleon-jade), in order to prevent you from even having to do what comes next.

Valérian has written an in-depth introduction to building and using your own theme, so I'll just cover the basics here.

All the theme has to do is expose a function implementing the following interface:

/**
 * @param {string} dest Directory to render theme in.
 * @param {object} ctx Variables to pass to the theme.
 * @return {promise} A Promises/A+ implementation.
 */
module.exports = function (dest, ctx) {
  ...
};

From there Themeleon takes charge of everything and allows you to write your theme without bothering with "low-level" considerations, like promises handling, raw fs calls, making sure the destination directory exists, and so on.

Then, it's all about creating a package.json file requiring some dependencies (including themeleon and your template engine, for instance themeleon-swigthemeleon-jade or whatever). As well as a directory containing an index.js file as explained in the docs. Then this JavaScript file will describe the process to generate the output.

In our default theme using themeleon-swig, it is as simple as:

var themeleon = require('themeleon')().use('swig');

module.exports = themeleon(__dirname, function (t) {
  t.copy('assets');
  t.swig('views/documentation/index.html.swig', 'index.html');
});

That's it! If you plan on building your own theme, you will be pleased to know we have made a boilerplate to help you getting started. Go ahead and read the docs, write a couple of lines and you'll be good to go. Also, feel free to ask for any help!

Gather Your Items Into Groups

One feature we've really  been looking forward to for a while now is the ability for you to gather your items into groups. At first, we grouped items according to their type: functionmixin and variable. When documenting a single API, it was fine but when running SassDoc on bigger projects it felt a little off.

Thus, you can now use the @group annotation followed by a string to define a group for an item thanks to the great work of Fabrice Weinberg. All items sharing the same group will be displayed in the same section. We keep the type grouping, so at the end of the day, it works like this: group > type > items. Meanwhile all items without a @group annotation will be gathered in an undefined group.

To allow you to name your groups the way you want, we added an aliasing system. For instance, if you declare a group with @group helpers, you can add an alias to it in the configuration so that it is displayed as "Helpers and Tools" for instance. This is especially useful when you want to rename the undefined default group into something more friendly like "General" or whatever.

Grunt, Gulp and Broccoli Plugins

If you are willing to incorporate SassDoc as part of your deployment process, you'll be pleased to know we already have a Grunt plugin, a Gulp plugin and a Broccoli plugin, all made by Pascal Duez. Using them is straightforward if you're familiar with the way each task runner works:

/* Gulp */
gulp.task('sassdoc', function () {
  return gulp
    .src('path/to/source')
    .pipe(sassdoc({
      dest: 'path/to/docs'
    }));
});
/* Grunt */
grunt.initConfig({
  sassdoc: {
    default: {
      src: 'path/to/source',
      dest: 'path/to/docs'
    }
  },
});
/* Broccoli */
var sassdoc = require('broccoli-sassdoc');
var docs = sassdoc(tree, options);

You can also add the same options as SassDoc regular CLI API, so feel free to read the README from the repositories to learn more about how to do so!

View Source Links

If there is one thing I really like in documentation of any kind it's the ability to go straight to the source code. It's therefore no surprise we've added a view source feature to SassDoc.

Because this is closely tied to the view, it is more like a theme feature than something from SassDoc itself. To put it simply, it needs a base path from the configuration file, then links to source are created using basePath +item.file.path, the latter being computed by SassDoc. For that reason, we suggest you always run SassDoc from the root of your project (it helps in many cases).

What’s Next?

Glad you asked! We have still pleeeenty of ideas for the future of SassDoc, and we are sure you have some interesting opinions yourself. Don't keep them for yourself; share them on the repository!

Meanwhile, we are working on:

  • an @output annotation, similar to @return but for mixins (#133)
  • making it possible to document Sass maps in a better way (#25)
  • giving the ability to preview the whole function/mixin directly from the documentation (#124)
  • ... your ideas? :)
Advertisement