savvy-js/README.md

Savvy - Style sheet documentation tool

# 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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/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.