savvy-js

Savvy - Document with style!

Savvy is a documentation tool for Css, Sass, Stylus, Less or any other styling language out there.

Why Savvy?

Does style sheet management in your project get out of hand? Are you aware of all the different classes in your style sheets? What states are implemented and how they look ?

Savvy will produce a convenient and powerful documentation site for your styles, allowing you to easily find and manage the classes in your style sheets. You can add live html examples and actually see how the class looks like.

How to install

You can install Savvy in your node project using npm

npm install savvy-js --save-dev

If you wish, you could use the grunt task

npm install grunt-savvy-js --save-dev

The Grunt task includes savvy-js inside it, so you don't need to install both.

See grunt-savvy-js on npm for more details on using the grunt task.

Running Savvy

Within NodeJs

Let's start with a code sample:

var savvy = require('savvy-js'),
    sourceFolder : "../web/styles",
    targetFolder : "../documentation",
    styleFiles : [ "../web/styles/style1.css", "../web/styles/style2.css" ],
    savvyOptions = {
        pattern : "*.scss",
        themeFolder: "../myCustomTheme"
    },
    savvyCallback = function(err){
        // Do stuff when Savvy is done and handle errors...
    };

savvy.run( sourceFolder, targetFolder, styleFiles, savvyOptions, savvyCallback);

This is what each argument means:

sourceFolder

Type : String

This is the folder that holds all your documented stylesheet source files (may it be the css, sass, less, stylus or any other format). You only have to give the root stylesheet folder path here, Savvy will dig out all the files recursively.

targetFolder

Type: String

This is a path for the compiled documentation.

styleFiles

Type: Array

This is an array of post-processed css files. You need to provide here the same list of css files that you use in your website or app. Savvy will use them to show you a live preview of how your css actually looks like.

options

Type: Object

An object of optional settings, including:

1. pattern [String] (default: "*.*") - a minimatch expression to help you specify only the files you wish to include in the documentation. By default Savvy will try to process all the files under the sourceFolder you provided. You can instruct it to take only sass files by providing "*.scss" as pattern for example.
2. patternOptions [Object] (default: { matchBase: true }) - these are options to be used with the pattern. see minimatch options for more details.
3. themeFolder [String] - you can provide an alternative theme folder here. See the Modifying Theme section later in this document.
4. debug [bool] - When true, savvy will report its progress in the console. This is useful when the code breaks and you want to know where.

callback

Type: function(err)

This is a callback function that Savvy will call when finished, or upon a fatal error.

Using Grunt

For more details, see the grunt-savvy-js page on NPM.

Documenting your code with Savvy

Structure

In savvy, you can divide your code into modules and sub-modules. Each module or sub-module can contain classes. Each class can contain states and child classes.

Module is the largest building block in your code. You can decide what is a module in your web application.

Sub-modules further divide the module into smaller parts.

Classes usually correspond with actual css classes. A class may reside in a sub-module, a module, or it can be a "loose" class that does not belong to any module.

States are different flavors of the same class. For example, if you have a Button class, and a PrimaryButton class, you can say that PrimaryButton is a state of Button. A state usually does nothing ( or at least nothing desirable ) on its own and is only meaningful when paired with the class it extends.

Child classes are usually smaller building blocks of a larger class. For example, if you have a ModuleDialog class, and a ModuleDialogCloseButton class, you may say that ModuleDialogCloseButton is a child of ModuleDialog. If you are struggling to decide whether a class should or should not be a child of another class, make it a child class only if it means nothing when you use it outside the scope of the parent class. CloseButton class might be useful outside a ModuleDialog, but ModuleDialogCloseButton class probably will not.

Where to document inside a stylesheet file?

Usually the documentation is written just above the declaration of a class, but actually Savvy doesn't care where you type the documentation comment. It will look only for documentation comments in the given files and ignore any other code or regular comments.

This means you can type a bunch of comments at the beginning or the end of the file or you can use a different file altogether if you find it convenient.

Syntax

Class

/**
 * This is where you type the description of the class.
 *
 * Use a blank row to insert a paragraph.
 *
 *    // Use 4 spaces to insert an html code sample
 *    <div class="className"></dv>
 *
 * @module ModuleName
 * @submodule SubModuleName
 * @class className
 */
 .className { ... }

A class can be assigned to a sub-module, a module or to none of them. If you wish to assign the class to a sub-module, you must provide both @module and @submodule statements. To assign it to a module, provide only the @module statement. To keep a "loose" class, don't provide any of them.

Module

/**
 * Just specify the module name in order to assign a class to a module
 *
 * @module ModuleName
 * @class className
 */
 .className { ... }

Sub-Module

/**
 * In order to assign a class to a sub-module, specify both the module
 * and sub-module names
 *
 * @module ModuleName
 * @submodule SubModuleName
 * @class className
 */
 .className { ... }

State

/**
 * Describe the state just like any other class, only add the @stateof statement.
 *
 * @class stateName
 * @stateof className
 */
 .stateName { ... }

If base class (stateof) name appears in several modules or sub-modules, add @module and @submodule statements accordingly. If the stateof class name is unique, you can omit the @module and @submodule statements and let Savvy attempt to automatically discover the parent.

Child Class

/**
 * Describe the child class just like any other class, only add the @parent statement.
 *
 * @class childClassName
 * @parent className
 */
 .childClassName { ... }

If base class (parent) name appears in several modules or sub-modules, add @module and @submodule statements accordingly. If the parent class name is unique, you can omit the @module and @submodule statements and let Savvy attempt to automatically discover the parent.

Modifying Theme

Modifying the default theme

Savvy allows you to specify a theme folder as one of the options in the run() method. For applying your brand name and colors, or other simple modification, it is recommended that you copy the entire theme folder from within the [your project path]/node_modules/savvy-js folder to a new location. You can then modify the theme as you wish, and provide the new location in Savvy's option:

savvy.run( "../source/css",
           "../documentation",
           ["../compiled/style.css"],
           { themeFolder: "[YOUR NEW THEME LOCATION HERE]" },
           function(err){ ... });

Creating an entirely new theme

To understand how to construct your own theme, you first have to understand what Savvy does when rendering:

1. Savvy copies the entire content of the themeFolder to the provided targetFolder
2. It then copies the provided styleFiles to a new folder in the targetFolder called compiledStyles
3. It opens index.html in the targetFolder and replace a string called {links} with links to the styleFiles
4. Finally, Savvy creates a file called data.js, that contains the entire structure of the Savvy documentation tree.

You can use this knowledge to write your own theme site using whatever technologies you like. As long as you provide an index.html file with the {links} placeholder within it Savvy will compile successfully.