search

thybzi / styledoc

Parser and showcase generator for JavaDoc-like comments in CSS, LESS, SASS etc.
MIT License
12 stars 0 forks source link

readme

StyleDoc: showcase your styles

Parser and showcase generator for JavaDoc-like comments in CSS, LESS, SASS etc.
Written on Javascript, available for both browser and NodeJS usage.

Implements StyleDoc draft standard: http://usestyledoc.org
(Previously inspired with concept idea of https://github.com/Joony/styledoc/)

Syntax example

/**
 * Buttons
 * All different kind of buttons used on website pages
 * @base     button     Normal button
 * @modifier .large     Large button
 * @modifier :disabled  Button unable to be pressed
 * @modifier .large:disabled Large button disabled
 * @example  <button>Button text</button>
 */
button {
    /* styles here */
}

You can see the full list of StyleDoc standard tags here: http://usestyledoc.org/tags (some of listed tags and features aren't supported yet, but planned for future support).

Besides normal /** docblocks, StyleDoc also supports /*! docblock format, which can be used in Stylus CSS preprocessor.

What does the tool do?

StyleDoc tool parses CSS file, extracting styledoc-blocks (like the one above) and creating showcase page based on them.

This page contains full list of documented elements and their variations, illustrated with live preview and markup example.

Live examples

All examples sources are available in examples directory of project repository.

More examples coming soon!

Quick start

First of all, you need a CSS file with some styledoc-blocks inside.

StyleDoc tool will create a showcase page based on such CSS file.
It can be created in two ways:

  1. Browser way (HTTP)
  2. NodeJS way (filesystem), including CLI usage

HTTP/browser way

In this mode, the tool generates showcase page dynamically inside a HTML file opened with browser.

All required files are loaded via HTTP requests (Ajax).

  1. Download the archive and unpack it (you only need styledoc.js and templates directory). You can also use Bower installation.
    Using js/styledoc/ directory is recommended (otherwise you'll need to reconfigure templates path).
  2. Download jQuery 1.11.1+ or 2.1.1+ (why these versions?)
    (needed only for separate showcase HTML file, no need to change version on other pages of your website)
  3. Download mustache.js
  4. Create a new HTML file with some basic markup, JS library links, and styledoc.showcaseFile() call. Something as simple as that:
<!DOCTYPE html>
<html>
<head>
    <title>My styles demo</title>
    <meta charset="utf-8">
    <script src="https://github.com/thybzi/styledoc/raw/master/js/jquery-1.11.1.js"></script>
    <script src="https://github.com/thybzi/styledoc/raw/master/js/mustache.js"></script>
    <script src="https://github.com/thybzi/styledoc/raw/master/js/styledoc/styledoc.js"></script>
</head>
<body>

<script>
    styledoc.showcaseFile('css/mystyle.css');
</script>

</body>
</html>

After that, just open the file with your browser (use http:// or https://, not file:///) and have fun!

CSS file path can be provided as an URL, or a path relative to current location.

Note that loading CSS file via cross-domain URL file may require a CORS header
(e.g. Access-Control-Allow-Origin: *).

For advanced configuration, see Configuration section.

Bower installation

StyleDoc is also available in Bower:

bower install styledoc

Filesystem/NodeJS way

In this mode, the tool generates showcase HTML files within the filesystem.

Browser renders these files faster, because they are "hardcoded" and not formed dynamically.

Also, if you have PhantomJS installed, you can minimize iframe loading lag and prevent page height changing (more details follow).

Required files are loaded via either filesystem or HTTP requests.

Installing

Assuming you already have NodeJS installed.

npm install styledoc

Basic usage

var styledoc = require('styledoc');
styledoc.showcaseFile('css/mystyle.css', {
    page_title: 'My presentation title'
});

CSS file path can be provided as an URL, or a path relative to current location.

The above code will create your presentation files in showcase/ directory (relative to the current directory).

You can change the output directory to any other relative path (trailing slash is optional).

var styledoc = require('styledoc');
styledoc.showcaseFile('css/mystyle.css', {
    page_title: 'My presentation title',
    output_dir: 'my/presentation/subdir/'
});

PhantomJS advantage

If you have PhantomJS installed in your system, you can use it to improve showcase generation.

It will pre-measure the height of each preview iframe item when generating them to achieve maximum rendering speed for showcase page (and also to avoid some possible client bugs).

To involve PhantomJS for showcase generation, just add one more option (use_phantomjs: true):

var styledoc = require('styledoc');
styledoc.showcaseFile('css/mystyle.css', {
    page_title: 'My presentation title',
    use_phantomjs: true
});

Advanced configuration

See Configuration section.

Windows users

StyleDoc requires JSDom module when in NodeJS mode.

JSDom installation could be a bit tricky on Windows (see corresponding section for more details).
If you are not enough lucky or patient, just use StyleDoc in HTTP/browser way.

Note that there are also some PhantomJS usage issues on Windows, but they don't prevent installing or running StyleDoc in non-PhantomJS-mode.

CLI usage

\@todo rewrite the section to describe CLI usage as primary way

StyleDoc can be used as command-line interface tool.

If StyleDoc is installed globally (npm install -g styledoc), use:

styledoc input_file [options]

Otherwise, from styledoc directory, use:

./bin/styledoc input_file [options]

Where:

To get more info, use:

styledoc --help

Or, from styledoc directory, use:

./bin/styledoc input_file [options]

Supported tags list

Also, first text line (e.g. with no tags) is considered to be the block title.
All text lines going after the block title are considered to be block description.
Any text lines, that go after the first tag encountered, are ignored.

See StyleDoc tag index at http://usestyledoc.org/tags/

Configuration

Set templates directory

To create a showcase, StyleDoc need a template.

It looks for this template on path set in styledoc.templates_dir property.

You can change this default value to any URL or relative path.

styledoc.templates_dir = 'my/custom/templates/dir';

@todo other configurable properties

showcaseFile() method options

Showcase options can be provided as second argument

styledoc.showcaseFile('css/mystyle.css', {
     /* options here */
});

Available options:

Creating your own template

@todo

Q & A

Can I use StyleDoc with LESS, SASS, etc.?

Yes, you can. The easiest way is just to compile it CSS, preserving CSS-style comments, and then apply StyleDoc to the resulting CSS file.

Why it is named StyleDoc? (not CSSDoc)

For now, StyleDoc actually supports only CSS docblocks. But in future it should also support docblocks for such LESS/SASS/Stylus constructs as mixins, functions etc. So, the scope of StyleDoc is broader than just CSS.

Does StyleDoc respect @import rules in CSS?

Yes, it does. The tool recursively loads and parses all imported CSS-files (as well as imports in that imported files, and so on).

Can I load CSS file by HTTP URL?

Yes, you can. Just provide an URL instead of relative path to CSS when calling styledoc.showcaseFile().
Also, if you use StyleDoc in browser mode, CORS headers are needed for getting that file.

How does live preview work?

Each element's preview is created in separate <iframe> with target CSS file linked and HTML content generated.

This approach prevents styles interference for main page and target CSS.

Also, StyleDoc tool preserves the same background color for main page and iframe live preview, so boudaries of that iframes are seemless.

Why there is a delay before live preview appears?

Previews are loaded within iframes, and it takes some time for them to render. After that, the tool needs to measure inner offset height of each preview and set this height value to the correspondent iframe element. And when this all is done, preview becomes visible.

Also, there is no reliable method for detecting the moment when rendering completes. That's why the tool sets a special delay after iframe reports it is "loaded". This delay defaults to 2000 ms, and could be changed with iframe_delay option for showcaseFile() method.

If your styles are light enough and seem to render faster, you may reduce this value, but keep in mind that some slower computers may need more time.

If the delay is too small, iframe could appear with wrong height (less or sometimes more than needed). But after you resizing page window, all iframe heights are remeasured (and probably fixed).

On the contrary, if your styles seem to be too heavy, or the computer is too slow, you can increase the value of iframe_delay.

But the best option is to use NodeJS mode with PhantomJS enabled. In this mode, PhantomJS pre-measures the height of each iframe, eliminating the necessity of additional iframe delay.

For that purpose, PhantomJS renders it within virtual "window" (size of which defaults to 1280×800, and can be overriden with phantomjs_viewport option for showcaseFile() method).

However, even these pre-measured iframe heights are also remeasured on window resize.

Why @state :hover doesn't work?

Modifiers available for showcase are limited to CSS modifications applicable by adding or altering HTML attributes. :hover or :active cannot be applied with attributes (unlike :checked, :disabled or :readonly), so they are mainly useless for showcase.
However, elements in showcase are full functional, so you can see the hover state of just by hovering the element by mouse.

I cannot install NodeJS version on Windows

StyleDoc uses two npm modules that could cause problems on Windows.

JSDom dependency

On Windows, there are some known problems when installing JSDom, which is required for NodeJS version of the tool. If you are lucky, following manuals could help (if not, you can still use StyleDoc in HTTP/browser way):

PhantomJS optional dependency

On Windows, there is also an issue when installing phantom (NodeJS library which used to communicate with PhantomJS).

However, PhantomJS usage is just an option giving you some advantages, so this dependency is marked optional, and StyleDoc installation won't fail if phantom couldn't be installed. You'll also see a warning message when generating showcase with use_phantomjs option enabled and no phantom package installed.

If you succeeded in fixing that issue, you can re-run npm install styledoc, which will try to install phantom package again.

Weak subdependency in PhantomJS

Also, even with phantom successfully installed on Windows you can still expirience problems like Error: Cannot find module 'weak'.

That can be solved by enabling phantomjs_noweak option for showcaseFile() method). More details follow here: https://github.com/sgentle/phantomjs-node#use-it-in-windows

Is there a grunt wrapper for npm module?

Yes, there is npm package grunt-styledoc that is usable for Grunt.

npm install grunt-styledoc

For configuration details and additional information, see project repo: https://github.com/thybzi/grunt-styledoc

Can StyleDoc be used as AMD module?

Yes, it is AMD-compatible.
@todo test it

Can StyleDoc be used as CommonJS module in browser?

Yes, it should work.
@todo test it

Why new version of jQuery is required?

StyleDoc requires jQuery version 1.11.1+ or 2.1.1+.
That is because showcase generator tool needs this particular change in jQuery Sizzle code:
https://github.com/jquery/sizzle/commit/ccb809ff416b06ca86abe54ce273c40f2271d3b5.
Without that, it cannot parse and apply CSS modifiers to HTML code.

I use an older version of jQuery on my website. What can I do?

  1. You can just use separate versions of jQuery for your website and showcase file.
  2. You can manually modify your jQuery file, reproducing this change:
    https://github.com/jquery/sizzle/commit/ccb809ff416b06ca86abe54ce273c40f2271d3b5;
    simplier, just find function tokenize( in jquery .js file, and add Sizzle.tokenize = tokenize; somewhere after (or before) this function.

Why npm module has such heavy dependencies?

For now, they all are needed for different reasons. I'll try to optimize these dependencies in future.

Why the code is so ugly?

For now, it just does its dirty work.

Hope that during the way from 0.0.1 to 1.0.0 it will become more neat and beautiful :)

Version history

TODO / Wishlist