Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 165 lines (125 sloc) 5.098 kB
ba93ff8 @darcyclarke Update readme
darcyclarke authored
1 ![DSS](http://cl.ly/image/2p0C122U0N32/logo.png)
2 - **[Official Logo](http://cl.ly/image/2p0C122U0N32/logo.png)**
933f321 @darcyclarke Update language in readme
darcyclarke authored
3 - **[NPM Package](https://npmjs.org/package/dss)**
82d9436 Added readme
Darcy Clarke authored
4
5ca4e07 @darcyclarke Update readme with npm stats
darcyclarke authored
5 [![NPM](https://nodei.co/npm/dss.png?downloadRank=true)](https://npmjs.org/package/dss)
6
f5c3eda @darcyclarke Slight mods to readme
darcyclarke authored
7 **DSS**, Documented Style Sheets is a comment guide and parser for CSS, LESS, STYLUS, SASS and SCSS code. This project does static file analysis and parsing to generate an object to be used for generating styleguides.
82d9436 Added readme
Darcy Clarke authored
8
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
9
53b81e6 @darcyclarke Update documentation
darcyclarke authored
10 ##### Table of Contents
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
11
53b81e6 @darcyclarke Update documentation
darcyclarke authored
12 - [Parsing a File](#parsing-a-file)
f5c3eda @darcyclarke Slight mods to readme
darcyclarke authored
13 - [`dss.detector`](#dssdetector-callback-)
14 - [`dss.parser`](#dssparser-name-callback-)
15 - [Other Projects](#other-projects)
53b81e6 @darcyclarke Update documentation
darcyclarke authored
16
17 ### Parsing a File
18
19 In most cases, you will want to include the **DSS** parser in a build step that will generate documentation files automatically (or you just want to play around with this returned `Object` for other means); Either way, we officially support a [Grunt Plugin](https://github.com/dsswg/grunt-dss) and a [Gulp Plugin](http://github.com/dsswg/gulp-dss).
20
f5c3eda @darcyclarke Slight mods to readme
darcyclarke authored
21 ### Examples
53b81e6 @darcyclarke Update documentation
darcyclarke authored
22
23 ##### Example Comment Block Format
82d9436 Added readme
Darcy Clarke authored
24
67804b2 @darcyclarke Modified readme, added new stylus example as we now support it as well
darcyclarke authored
25
26 ```scss
27 //
28 // @name Button
29 // @description Your standard form button.
30 //
31 // @state :hover - Highlights when hovering.
32 // @state :disabled - Dims the button when disabled.
33 // @state .primary - Indicates button is the primary action.
34 // @state .smaller - A smaller button
35 //
36 // @markup
37 // <button>This is a button</button>
38 //
39 ````
40
53b81e6 @darcyclarke Update documentation
darcyclarke authored
41 ##### Example Usage
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
42
8cca9eb @darcyclarke Update readme broken javascript syntax highlighting
darcyclarke authored
43 ```javascript
53b81e6 @darcyclarke Update documentation
darcyclarke authored
44 // Requirements
ba93ff8 @darcyclarke Update readme
darcyclarke authored
45 var fs = require( 'fs' );
53b81e6 @darcyclarke Update documentation
darcyclarke authored
46 var dss = require( 'dss' );
47
48 // Get file contents
49 var fileContents = fs.readFileSync( 'styles.css' );
50
51 // Run the DSS Parser on the file contents
52 dss.parse( fileContents, {}, function ( parsedObject ) {
53
54 // Output the parsed document
55 console.log( parsedObject );
ba93ff8 @darcyclarke Update readme
darcyclarke authored
56
57 });
58
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
59 ````
60
53b81e6 @darcyclarke Update documentation
darcyclarke authored
61 ##### Example Output
67804b2 @darcyclarke Modified readme, added new stylus example as we now support it as well
darcyclarke authored
62
c64d847 @jthiller JSON Syntax highlighting for the Generated Object
jthiller authored
63 ```json
67804b2 @darcyclarke Modified readme, added new stylus example as we now support it as well
darcyclarke authored
64 {
65 "name": "Button",
66 "description": "Your standard form button.",
67 "state": [
68 {
69 "name": ":hover",
70 "escaped": "pseudo-class-hover",
71 "description": "Highlights when hovering."
72 },
73 {
74 "name": ":disabled",
75 "escaped": "pseudo-class-disabled",
76 "description": "Dims the button when disabled."
77 },
78 {
79 "name": ".primary",
80 "escaped": "primary",
81 "description": "Indicates button is the primary action."
82 },
83 {
84 "name": ".smaller",
85 "escaped": "smaller",
86 "description": "A smaller button"
87 }
88 ],
89 "markup": {
90 "example": "<button>This is a button</button>",
91 "escaped": "&lt;button&gt;This is a button&lt;/button&gt;"
92 }
93 }
94 ````
53b81e6 @darcyclarke Update documentation
darcyclarke authored
95 #### dss.detector( callback )
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
96
53b81e6 @darcyclarke Update documentation
darcyclarke authored
97 This method defines the way in which points of interest (ie. variables) are found in lines of text and then, later, parsed. **DSS** dogfoods this API and the default implementation is shown below.
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
98
53b81e6 @darcyclarke Update documentation
darcyclarke authored
99 ###### Default Detector:
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
100
101 ```javascript
53b81e6 @darcyclarke Update documentation
darcyclarke authored
102 // Describe default detection pattern
103 // Note: the current line, as a string, is passed to this function
104 dss.detector( function( line ) {
105
106 if ( typeof line !== 'string' ) {
107 return false;
108 }
109 var reference = line.split( "\n\n" ).pop();
110 return !!reference.match( /.*@/ );
dd27e0c @darcyclarke Updated readme with link to grunt-dss and some more information about…
darcyclarke authored
111
112 });
113 ````
114
53b81e6 @darcyclarke Update documentation
darcyclarke authored
115 #### dss.parser( name, callback )
116
117 **DSS**, by default, includes 4 parsers for the `name`, `description`, `state` and `markup` of a comment block. You can add to, or override, these defaults by registering a new parser. These defaults also follow a pattern which uses the `@` decorator to identify them. You can modify this behaivour providing a different callback function to `dss.detector()`.
c7e28a3 @darcyclarke Add note about Sublime Text auto-complete comment block plugin
darcyclarke authored
118
53b81e6 @darcyclarke Update documentation
darcyclarke authored
119 `dss.parser` expects the name of the variable you're looking for and a callback function to manipulate the contents. Whatever is returned by that callback function is what is used in generate JSON.
c7e28a3 @darcyclarke Add note about Sublime Text auto-complete comment block plugin
darcyclarke authored
120
53b81e6 @darcyclarke Update documentation
darcyclarke authored
121 ##### Callback `this`:
c7e28a3 @darcyclarke Add note about Sublime Text auto-complete comment block plugin
darcyclarke authored
122
53b81e6 @darcyclarke Update documentation
darcyclarke authored
123 - `this.file`: The current file
124 - `this.name`: The name of the parser
125 - `this.options`: The options that were passed to `dss.parse()` initially
126 - `this.line`:
127 - `this.line.contents`: The content associated with this variable
128 - `this.line.from`: The line number where this variable was found
129 - `this.line.to`: The line number where this variable's contents ended
130 - `this.block`:
131 - `this.block.contents`: The content associated with this variable's comment block
132 - `this.block.from`: The line number where this variable's comment block starts
133 - `this.block.to`: The line number where this variable's comment block ends
134
135
136 ##### Custom Parser Examples:
137
138 ```javascript
139 // Matches @version
140 dss.parser( 'version', function () {
141
142 // Just returns the lines contents
143 return this.line.contents;
144
145 });
146 ````
147
148 ```javascript
149 dss.parser( 'link', function () {
150
151 // Replace link with HTML wrapped version
152 var exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
153 this.line.contents.replace(exp, "<a href='$1'>$1</a>");
154 return line;
155
156 });
f5c3eda @darcyclarke Slight mods to readme
darcyclarke authored
157 ````
158
159 ### Other Projects
160 - [Grunt Plugin](http://github.com/dsswg/grunt-dss)
161 - [Gulp Plugin](http://github.com/dsswg/gulp-dss)
162 - [Sublime Text Plugin](https://github.com/sc8696/sublime-css-auto-comments)
163 - [UX Recorder](http://github.com/dsswg/dss-recorder)
164 - [UX Player](http://github.com/dsswg/dss-player)
Something went wrong with that request. Please try again.