sassdocjs

Sass source comment documentation generator

#

sassdocJs is a nodejs command-line (CLI) app that will parse jsDoc style comments* found in your .scss source files, and use them to create a structured set of Html-based documentation. It's aim is to provide an easy way to catalog your growing library of sass mixins, functions, placeholders, etc, while complimenting whatever workflow, or Sass/Css/OOCSS standardization you may have adopted.

I've tried to keep things extensible: there's a default set of 'language definitions', such as @mixin, %placeholder, or #id, but it's simple to construct custom definitions. A theme-able Html/Handlebars.js template is included. Finally, the parsed documentation result is saved as plain JSON, so you can easily work it into whatever front-end you fancy.

Features

  • Document OOCSS-style naming conventions (BEM, SMACSS, custom)

  • Extensible with custom doc tags

  • Saved as JSON - use the included template or your own

Website/Demo: sassdocjs.com

*currently not // comments - see known issues below.

sassdocJs is built with nodeJs & can be installed with npm

$ npm install -g sassdocjs
$ git clone git://github.com/mattbieber/sassdocjs.git

To use sassdocJs, open up a shell and run the following command.

$ sassdocjs [path] [options]

With no arguments , sassdocJs will recursively search the current directory for Sass source files, and output generated documentation to ./doc

There's a fair amount of configuration switches, see below on how to supply them via a config file.

OptionDescription
-n, –namename of the project
-u, –logologo file url to appear in documentation header
-d, –descproject description
-v, –versionversion of the documentation
-a, –authproject author(s)
-b, –contribproject contributors
-s, –statusproject status
-x, –excludefile pattern for exclusion
-i, –includefile pattern for inclusion
-o, –outpath to write generated docs to
-t, –templpath to output template directory
-r, –recurserecurse working directory for sass sources
-p, –prefixcategorize by prefix (e.g. m- = module)
-c, –configsave .yml config file in working directorytrue
-l, –logtoggle logging
-y, –verboselogging verbosity
-m, –limitset the allowed file parsing concurrency
-h, –helpshow sassdocjs usage options

You can simplify configuration by putting a YAML config file - config.yml - at the root of your projects’ ource folder. See the one included in the example for file’s layout, or run sassdocjs --config and fill out the created file.

When parsing files, sassdocJs pulls out comments using 'definitions' found in lib/lang/defs. Definitions can be supplied for both in-comment tags, or for a keyword prefix character, as in # and %, for Css Ids and Sass placeholders. The following are provided:

  • $ Sass variable
  • % Sass placeholder
  • . Css class
  • # Css Id
  • @ Sass mixin/function
  • @module Define a file as a module
  • @param Sass mixin/function argument
  • @returns Sass mixin/function return value
  • @example Code example
  • @usedin Location(s) the documented item can be found

It’s fairly trivial to supply your own documentation tag definitions should you wish. Any def_*.js file found by the parser will be included as a definition and have it's rules applied during validation. Definition files should implement lib/lang/defs/_def.js.

 
/**
 * language definition file for a Sass mixin
 * http://sass-lang.com/documentation/file.SASS_REFERENCE.html#mixins
 *
 * @module lib/lang/defs/def_mixin
 */
 
var _sd = require('../../env/const'),
    definitionBase = require('./_def').definitionBase;
 
/**
 * @constuctor
 */
function _lang_def() {
 
    /* implement base */
    definitionBase.call(this, {
        type_def: 'mixin',
        value: 64, //@ 
        name_position: 2,
        context: _sd.CONTEXT.FIRST_CLASS,
        canHaveValue: _sd.VALIDATION.REQUIRED,
        canHaveDescription: _sd.VALIDATION.OPTIONAL,
        canHaveMeta:  _sd.VALIDATION.OPTIONAL
 
    });
 
    /* definitions must implement validate */
    this.validate = function() {
 
    };
 
 
/* exports */
module.exports = new _lang_def();
 

With the --prefix option, sassdocJs will parse and group your files according to word prefix entries placed in lib/lang/prefix.js. I've included SMACSS-ish entries, but anything can be supplied.

 
  module.exports = {
  
    // smacss 
    'm-'    :   'module',
    'l-'    :   'layout',
    's-'    :   'state',
    'is-'   :   'state'
  };
 

The prefixed grouping is called 'category' in the docs

A few resources regarding OOCSS-style naming:

You can provide an @usedin entry in your comment block with a comma-separated value of locations (e.g. header, shopping cart, home page). sassdocJs will include that as a grouping option in the generated docs.

The use location grouping is called 'used' in the docs

The included Handlebars template is pretty straight-forward. It uses the generated sassdocjs-data.js as it's data source. I've included some rudimentary themeing ability which you can find in the ./Sass directory. See one of the existing theme files for reference.

If you do customize, you'll want to run $ grunt build in the template directory to compile the Sass and move it to the build folder.

You can run the included test with make or grunt:

$make / $grunt test

Additional fixtures can be put in ./test/parse.spec.js

For eample useage, please see the commented Sass source and Yaml config file in ./example.

*I went with jsDoc-style comments for the simple reason that I prefer them to the Sass // variety. The (obvious) drawback is that the Sass compiler won't strip these out upon compilation. I've got some ideas in mind for this on the roadmap, but please contribute if you wish. I also decided to eschew support for the older syntax style (.sass). Feel free to fork the repo and add it.

This is 0.1.0 code - please get in touch with any issues you encounter.

Note: This has been minimally tested in Windows

Following is what's planned.

  • Add support for standard Sass // comment blocks.
  • Ability to strip sassdocJs comment blocks //* */ on save so they don't end up in the pre-compiled Sass files.
  • Move name prefixing setting to config file.

Licensed under the MIT License (MIT)

Website: sassdocjs.com