# ui-docs

Styleguide Generator for UI Components.

ui-docs is still a **WORK IN PROGRESS**.


## Features

- Dynamic @directives
- @state and @modifier directives
- Supports Custom templates
- Focused on Modular CSS Architectures
- Use Markdown in descriptions
- Write less markup using Handlebars helpers
- Give some hierarchy to your CSS using dot paths
- One single HTML page for each component (or flatten a tree into a single page)
- Works with any CSS-preprocessing language or with CSS directly
- Easily extendible. Custom translators for each @directive.


## Installation

    $ npm install ui-docs


## Usage

**ui-docs** is a node package, you can write a small `.js` file and run it from
the command line. See [test/ui-docs.js](example/ui-docs.js)

Or if you are using [Grunt](http://gruntjs.com), there is a ui-docs grunt plugin
[here](https://github.com/vieron/grunt-ui-docs).


## Example

```css
/**
 * Icon
 * Lorem ipsum Non do id tempor laboris do ut veniam in sint fugiat fugiat
 * adipisicing elit Excepteur.
 *
 * @modifier .Ico-edit Lorem ipsum dolor sit amet
 * @modifier .Ico-settings Lorem ipsum dolor sit amet
 *
 * @snippet
 * <i class="Ico {{classes}}"></i>
 *
 * @id components.icon
 */
```


```css
/**
 * Button
 * Lorem ipsum Non do id tempor laboris do ut veniam in sint fugiat fugiat
 * adipisicing elit Excepteur.
 *
 * @state :hover
 * @state .js-isDisabled Lorem ipsum dolor sit amet
 *
 * @modifier .btn--success Lorem ipsum dolor sit amet
 * @modifier .btn--cancel Lorem ipsum dolor sit amet
 *
 * @theme dark
 * @snippet
 * <a class="button {{classes}}">Button</a>
 *
 * @theme light
 * @snippet
 * <button class="button {{classes}}">Button</button>
 *
 * @theme dark
 * @snippet
 * <a class="button {{classes}}">
 *     {{use 'components.icon Ico--edit'}}
 *     <span>Button</span>
 * </a>
 *
 * @id components.button
 */
 ```


 ```css
 /**
  * Button Group
  * Lorem ipsum Non do id tempor {{link_to 'components.button'}} laboris do ut veniam in sint fugiat fugiat
  * adipisicing elit Excepteur.
  *
  * @modifier .BtnGroup--compact Lorem ipsum dolor sit amet
  * @modifier .BtnGroup--fullWidth Lorem ipsum dolor sit amet
  *
  * @snippet
  * <div class="BtnGroup {{classes}}">
  *     {{#repeat 4}}
  *         {{use 'components.button'}}
  *     {{/repeat}}
  * </div>
  *
  * @id components.buttonGroup
  */
```


## Options

| Name                      | Type               | Default                                         | Description
|:-------------             |:-------------      |:-----                                           |:---------------
| **title**                 | `String`           | `'ui-docs'`                                     | Title used for the Styleguide.
| **docsPath**              | `String`           | `'docs/styleguide'`                             | Path where generated Styleguide will be located.
| **docsAssetsPath**        | `String`           | `'assets/'`                                     | Path where your project assets are copied to. Relative to `docsPath`.
| **docsUIDocsAssetsPath**  | `String`           | `'css-docs/'`                                   | Path where ui-docs assets are copied to. Relative to `docsAssetsPath`.
| **templatePath**          | `String`           | `path.join(__dirname, '../template/')`          | Path to the theme folder used to generate the docs.
| **rawAssetsDir**          | `String`           | `'assets/'`                                     | Path to your project raw assets.
| **extrasPath**            | `String`           | `'docs/extras/'`                                | Path to directory where extra files (useful to load extra html/js/css for demo purposes) are located.
| **js**
| **js.rawDir**             | `String`           | `'js/'`                                         | Path to raw javascript files. Relative to `rawAssetsDir`.
| **js.validExtensions**    | `Array`            | `['.js', '.coffe']`                             | Valid extensions for javascript files.
| **js.ignore**             | `Array`            | `['**/vendor/**', '**/vendor-setup/**']`        | Ignore files from being parsed. Using [multimatch](https://github.com/sindresorhus/multimatch)
| **css**
| **css.rawDir**            | `String`           | `'css/'`                                        | Path to raw CSS files. Relative to `rawAssetsDir`.
| **css.validExtensions**   | `Array`            | `['.scss', '.css', '.sass', '.styl', '.less']`  | Valid extensions for CSS files.
| **css.ignore**            | `Array`            | `['**/bourbon/**']`                             | Ignore files from being parsed. Using [multimatch](https://github.com/sindresorhus/multimatch)
| **css.builtFilePaths**    | `Array`            | [`assets/css/built.css`]                        | Paths where final build/compiled CSS files will be copied to. To use in the styleguide.


## Doc block variables (for templating)

- title (first line of description)
- description
- name (one word, from styleguide)
- modifier
    - classes
    - name
    - description
- state
    - classes
    - name
    - description
- usage
- snippet
- snippet_highlighted
- embeds
- flatten
- nopreview
- styleguide (components.button)
- theme (light/dark/gray)
- line
- filePath
- absoluteFilePath
- treePath (components.childs.button)


## Development

Checkout the project and go to:

    $ git clone git@github.com:vieron/ui-docs.git
    $ cd ui-docs/example
    $ git clone git@github.com:vieron/ui-docs.git docs
    $ cd docs
    $ git checkout gh-pages


Compile example sass

    $ cd example
    $ sass --watch assets/sass/demo.scss:assets/css/built.css

Generate docs

    $ node ui-docs.js


## TO-DO

* @extends and @depends directives
* think in a way to have different markup for modifiers of the same CSS object
* helper for lorem ipsum
* refactor
* error reporting
* write tests, a lot of tests
* @experimental and @deprecated directive
* @index directive to render TOC
* option to generate a JSON representation instead of generate HTML docs
* copy code snippet (zeroclipboard)