ClareWall.org

StyleDocco is a tool for the generation of documentation and style guide documents from your CSS stylesheets. It was written by Jacob Rask and is available as a Node package under the MIT license. It includes support for SASS, SCSS, Less and Stylus.

Assuming you have first installed Node.js, you can install StyleDocco globally by simply running:
npm install -fg styledocco

The next stage is to write some stylesheet comments. Later, StyleDocco will be used to parse these comments through Markdown and display them in a generated HTML document.

Markdown converts text with four spaces at the front of each line to code blocks. StyleDocco also supports the GitHub Flavored Markdown convention of wrapping text with fenced blocks (```) to achieve the same effect. Whichever way you choose to do it, you can use this technique to write HTML code in your comments, and StyleDocco will show you a preview with the styles applied, the example HTML code underneath, and the CSS markup next to it. Whitespace before a comment block will ensure it is excluded from the documentation.

Finally, to generate the HTML style guide documents, you will need to run StyleDocco. An example command might be:
styledocco -n "My Project" -o mydocs styles
where "My Project" is the name of your project, mydocs is the name of your output directory and styles is the name of the directory containing your stylesheets.

For example, the following stylesheet:

/* Buttons
==========
Buttons for performing actions in the site.

Identifies the primary action in a set of buttons.

    <button class="btn primary">Primary</button>
*/
.btn.primary {
    background: #0000FF;
    color: #FFFFFF;
    border: 2px outset #000000;
}

/* Identifies the cancel action in a set of buttons.

    <button class="btn cancel">Cancel</button>
*/
.btn.cancel {
    background: #FF0000;
    color: #FFFFFF;
    border: 2px outset #000000;
}

/* News
==========
 Provides extra visual weight and identifies a news article.

    <div class="news">A news article</div> 
*/
div.news {
    background: #FFCC00;
	padding: 5px;
}

generates the following styleguide:

Each preview includes a drag handle to help you see the effect of re-sizing it. If your project includes a README.md file, it will be used as the base for your index page.

At the bottom of the screen, there are various different options you can click to view it as it might appear on, for example, a smartphone or a laptop.

While I like StyleDocco very much, I have come across a few issues while trying it out in its current state, the first one being most serious:

• Using IE9 or IE10, the previews are not currently visible. I haven’t yet tried it in earlier versions of IE as I don’t have VMs setup at home, but setting the browser mode to IE7 or IE8 does not resolve the issue.
• In Chrome, the previews can be resized larger but not smaller.
• In Firefox, resizing the browser does not resize the previews.

I would not want to introduce StyleDocco in a work environment without first looking at whether I could resolve the Internet Explorer issues.

If I were to introduce StyleDocco in a work environment, I would want to include it as part of the build process. This would enable other developers to view the documentation without necessarily having to set things up on their machine. However simple it is to set up a machine with Node.js and StyleDocco, I have found new ideas less likely to take off, the more obstacles there are to doing them. Also, once it becomes part of the build process, it effectively becomes the standard.

I look forward, next, to taking a look at another tool: Kalei Style guide by Thomas Davis.

Read Full Post »