sassdoc

SassDoc

Like JSDoc for your Sass files.

• Usable out of the box.
• Highly customisable.
• Reasonably fast.
• Fully themable.
• Integrated with Grunt/Gulp/Broccoli or directly Node.

master: develop:

How does it work?

SassDoc parses your source folder to grab documentation-specific comments. From there, it builds a data tree, that gets enhanced and filtered before being passed to the view. So you end up with a fully styled HTML document located at your destination folder.

Usage

Command line

Install

npm install -g sassdoc

Generate Documentation

sassdoc <src> <dest> [options]

Arguments:

1. <src> Path to your Sass folder.
2. <dest> Path to the destination folder.

Options:

• --version: Show version.
• -h, --help: Bring help.
• -v, --verbose: Run in verbose mode.
• -c, --config: Path to JSON file containing variables to be passed to the view.
• -t, --theme: Theme to be required. It will override the configuration value.
• --no-update-notifier: Do not run the update notifier check.

Node

Install

npm install sassdoc --save

Use The Raw Data

var sassdoc = require('sassdoc');

sassdoc.parse(__dirname + '/sass').then(function (items) {
  console.log(items);
})

Generate Documentation

var config = {
  display: {
    access: ['public', 'private'],
    alias: false,
    watermark: true,
  },

  package: 'path/to/package.json', // Defaults to `./package.json`
  theme: 'theme-name', // Defaults to `default`
};

var sassdoc = require('sassdoc');
sassdoc.documentize(source, dest, config);

Grunt, Gulp, Broccoli

See grunt-sassdoc, gulp-sassdoc, broccoli-sassdoc.

Documentating your items

See Wiki.

Customising the view

See Wiki.

Example

/**
 * Adds `$value` at `$index` in `$list`.
 *
 * @author Hugo Giraudel
 *
 * @requires {function} is-true
 *
 * @param {List}   $list  - list to update
 * @param {Number} $index - index to add
 * @param {*}      $value - value to add
 *
 * @throws List index $index is not a number for `insert-nth`.
 *
 * @return {List | Null}
 */

@function insert-nth($list, $index, $value) {
  // ...
}

/**
 * Defines whether the lib should support legacy browsers (e.g. `IE 8`).
 *
 * @since 1.3.37
 *
 * @todo Nothing. It's awesome.
 *
 * @link https://github.com/SassDoc/sassdoc SassDoc
 *
 * @type Bool
 */
$legacy-support: true !global;

Built with SassDoc

• GUSS from The Guardian
• SassyIcons from Pascal Duez
• SassyFilters from Pascal Duez
• SassyLists from Hugo Giraudel
• css-patterns from madebymany
• scss-components from Tim Hartmann
• yy from Astina
• Sassy Starter from archermalmo

Credits

• Valérian Galliat
• Fabrice Weinberg
• Pascal Duez
• Hugo Giraudel

Changelog

1.6.1

• Fixed a bug where some descriptions didn't allow line breaks (#209)