Parser and showcase generator for JavaDoc-like comments in CSS, LESS, SASS etc.
npm install styledocStyleDoc: 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
---------------
``css`
/**
* 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 {
/ 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
---------------
* CSS source: main.css
Built from following LESS files:
button.less,
checkbox.less,
__mixins.less,
__build.less
* Showcase pages generated in different ways:
Browser
(source),
NodeJS
(source),
NodeJS + PhantomJS
(source)
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
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. js/styledoc/
Using directory is recommended (otherwise you'll need to reconfigure templates path). styledoc.showcaseFile()
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 call. Something as simple as that:
`html
`
After that, just open the file with your browser (use 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
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
`javascript`
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).
`javascript`
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):`javascript`
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:
* input_file is relative path or absolute URL to CSS fileoptions
are one or more options as described in Configuration* section. preview_padding
(Note they are named is cli-manner, e.g. becomes --preview-padding etc)`
To get more info, use:
styledoc --help
Or, from styledoc directory, use:`
./bin/styledoc input_file [options]
Supported tags list
---------------
* @section: Section number and title within showcase file
Example: @section 2.3 Buttons @base
Sections are sorted by section number
If section title is omitted, block title or title is used instead@base button Normal button
* @base: Base CSS selector and title
Example: @modifier .large Large sized button
Base selector can contain element name, class or whatever.
All modifiers and states are applied to this kind of element.
* @modifier: CSS selector and title for modifier
Example: @base
A selector that modifies selector by adding class(es) or/and ID or/and any other CSS modification that can by applied by creating or altering some HTML attribute(s). @state .active Active state of the button
Any number of modifiers can exist within the same section.
* @state: CSS selector and title for state
Example: @pseudo
Alias: :checked
A special kind of modifier that doesn't represent any valuable variation of element, but only some special state (like or .active). @example
All modifiers are sequentially applied within each showcase subsection, instead of creating a separate subsection.
Any number of states can exist within the same section.
Just like common modifiers, can only represent CSS modification applicable with HTML attributes.
* @example: HTML code representing the usage of element
Example: @markup
Aliases: , @presentation, @preview @base
Should contain HTML markup for CSS selector determined in . @author John Smith
Gets altered by all modifiers and states documented, creating code for HTML markup example and also live preview.
Can be multiline (relative indents are respected). Can begin from the next line after the tag.
* @author: Name, email, etc. of the code block author
Example: @version 1.4
Multiple instances are allowed within the same section.
* @version: Version of code block (if you need to specify it by some reason)
Example:
* @since: Code version element exists since
Example:
* @deprecated: Beginning code version and/or reasons for element deprecating
Example: @see http://stackoverflow.com/a/428032
Either version or description can be omitted.
* @see: Some reference to be mentioned
Example: @todo Replace sprite images with pure CSS
Multiple instances are allowed within the same section.
* @todo: Some matters to be improved within the code
Example: @fixme IE9 fails to draw this element correctly
Multiple instances are allowed within the same section.
* @fixme: Some things needed to be fixed within the code
Example:
Multiple instances are allowed within the same section.
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
---------------
It looks for this template on path set in styledoc.templates_dir property.js/styledoc/templates/
For HTTP/browser mode*, default path is (relative to the HTML file).templates/
For FS/NodeJS mode*, default path is subdir inside module directory.
You can change this default value to any URL or relative path.
`javascript`
styledoc.templates_dir = 'my/custom/templates/dir';
In HTTP/browser mode*, path value is relative to the HTML file.
In FS/NodeJS mode*, path value is relative to output directory.
@todo other configurable properties
javascript
styledoc.showcaseFile('css/mystyle.css', {
/ options here /
});
`
#### Available options:
* $container: (HTTP mode only) JQuery element for root showcase container
Default value:
* output_dir: (FS mode only) Path for creating to showcase files, relative to current location
Default value:
* template: Name of showcase page template
Default value:
* language: Language to apply when creating page (should exist in template's directory)
Default value: 'en'
* doctype: Live preview target doctype (should exist in template's directory).
Default value: 'html5'
* page_title: Main title () of showcase page
Default value for HTTP mode: document.title
Default value for FS mode: ''
* css_url_http: (FS mode only) HTTP(S) path to CSS file to use in preview (detected automatically by default)
Default value:
* iframe_delay: Delay (ms) before refreshing iframe height
This delay is needed to render preview item iframe page, measure its height, and then apply this height to