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.

By default, sassdocJs will group your documentation by kind (mixin, var, etc.), name, and file. It's also possible to group by useage location (header, navbar, etc.), and by OOCSS-style naming conventions (m-odule, l-ayout, etc.) as used in BEM, SMACSS and the like.

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.

* currently not // comments - see here

Installation

sassdocJs is built with nodeJs & can be installed via npm or download the source.

with npm

npm install -g sassdocjs

Clone or fork on GitHub

git clone git://github.com/mattbieber/sassdocjs.git

Usage

To use sassdocJs, open up a shell and run the following command. There's a number of command line options available, see below.

sassdocjs [path] [options]

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

Options

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

Option Description
-n, –name name of the project
-u, –logo logo file url to appear in documentation header
-d, –description project description
-v, –version version of the documentation
-a, –auth project author(s)
-b, –contrib project contributors
-s, –status project status
-x, –exclude file pattern for exclusion
-i, –include file pattern for inclusion
-o, –out path to write generated docs to
-t, –template path to output template directory
-r, –recurse recurse working directory for sass sources
-p, –prefix categorize by prefix (e.g. m- = module)
-c, –config save .yml config file in working directorytrue
-l, –log toggle logging
-y, –verbose logging verbosity
-m, –limit set the allowed file parsing concurrencey
-h, –help show sassdocjs usage options

Options config file

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

Language Definitions

When parsing comments, 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
/**
 * 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();

OOCSS Naming Conventions

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.

1
2
3
4
5
6
7
8
9
module.exports = {

	// smacss
	'm-'    :   'module',
	'l-'    :   'layout',
	's-'    :   'state',
	'is-'   :   'state'

};

The prefixed grouping is called 'category' in the docs

More info

A few resources regarding OOCSS-style naming:
SMACSS.com Taking Sass to the Next Level with SMURF and @extend Fifty Shades of BEM

Use Location

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

Template

The included Handlebars template is pretty straight-forward. It uses the generated sassdoc-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.

Test

You can run the included test with make or grunt:

$make / $grunt test

Additional fixtures can be put in parse.spec.js

Examples

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

Known Issues

*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.0.1 code so please get in touch with any issues you encounter.

Roadmap

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.