A style-guide generator that uses Swig.js
The Panopta style-guide generator is a tool that scrapes documention from your source files which it then uses to generate a style-guide, capable of gathering documention from, essentially, any type of file, which allows you to easily document your JavaScript, HTML, or whatever other type of component that you'd like documented.
This plugin requires Grunt ~0.4.5
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-panopta-style-guide-generator --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-panopta-style-guide-generator');
In your project's Gruntfile, add a section named style_guide
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
style_guide: {
main: {
options: {
path: { ... },
copy: {
'assets/css/modern.css': 'web/assets/css/modern.css'
}
},
files: [
{
expand: true,
cwd: '',
src: [
'assets/scss/**/*.scss',
'assets/scss/**/*.less',
'assets/css/**/*.css'
]
}
]
}
}
});
Type: Object
Default value: { src: '_styleguide/', dest: 'docs/styleguide/' }
Paths used by the style-guide generator
Type: String
Default value: _styleguide/
The location the styleguide source code is to be placed. Must include a trailing slash.
Type: String
Default value: docs/styleguide/
The location the styleguide will be built to. Must include a trailing slash.
Type: Object
Default value: undefined
An object containing assets that should be copied over to the style-guide destination folder.
Note the example below. The right hand assignment is the path to the asset that should be copied; the left hand assignment is the path to where the asset should be copied to within the style-guide destination folder.
grunt.initConfig({
style_guide: {
main: {
options: {
copy: {
'assets/css/modern.css': 'web/assets/css/modern.css'
}
}
}
}
});
grunt.initConfig({
style_guide: {
main: {
options: {
copy: {
'assets/css/modern.css': 'web/assets/css/modern.css'
}
},
files: [
{
expand: true,
cwd: '',
src: [
'assets/scss/**/*.scss'
]
}
]
}
}
});
Below, the Panopta style-guide generator is configured to output the style-guide as well as its source in a custom location.
grunt.initConfig({
style_guide: {
main: {
options: {
path: {
src: 'some/path/',
dest: 'styleguide/'
},
copy: {
'assets/css/modern.css': 'web/assets/css/modern.css'
}
},
files: [
{
expand: true,
cwd: '',
src: [
'assets/scss/**/*.scss'
]
}
]
}
}
});
The Panopta style-guide generator searches for name/value combinations within your source files; these name/value combinations are then used within the component.html
Swig template. Note that all values are parsed as markdown. Name/value combinations are expected to take the following format.
/*
{% Name: Btn %}
{% Category: elements %}
{% Description: <button>I'm a button</button> %}
*/
.btn {
color: blue;
}
Specifically, each name/pair value is expected to be enclosed within {%%}
markings and separated by a :
. As components can be lengthy, it's not always ideal to inline documenation in your CSS/SCSS/LESS files. As such, the Panopta style-guide generator allows you to load documentation from markdown files.
/*
{% Name: Btn %}
{% Category: elements %}
{% Description: relative/path/to/markdown-file.md %}
*/
.btn {
color: blue;
}
As previously mentioned, the Panopta style-guide generator can accept any number of name/value combinations, though it demands that name, category and description are used. Each name/value combination is available within the generated Swig templates via the component
global. Use name/value combinations as you wish.
/*
{% Name: Btn %}
{% Category: elements %}
{% Version: 1.0.0 %}
{% Author: Michael Jordan %}
{% Description: relative/path/to/btn_docs.md %}
*/
.btn {
color: blue;
}
The previous examples show name/value combinations within CSS comments. The Panopta style-guide generator is capable of scraping documention from within all comment types:
//-------------------------------------------------
// Btn
//-------------------------------------------------
//
// {% Name: Btn %}
//
// {% Category: elements %}
//
// {% Version: 1.0.0 %}
//
// {% Author: Michael Jordan %}
//
// {% Description: relative/path/to/btn_docs.md %}
//
//-------------------------------------------------
.btn {
color: blue;
}
<!--
{% Name: Btn %}
{% Category: elements %}
{% Description: <button class="btn">Im' a button</button> %}
-->
<button class="btn">Im' a button</button>
The Panopta style-guide generator was inspired by pattern lab, which categorizes UI components as atoms, molecules, organisms, templates, and pages. The Panopta style-guide generator uses a similar set of categories: elements, molecules, and organisms. In order for a component to show up in the generated style-guide, it must be placed in one of these categories.
See atoms
See molecules
See organisms
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
(Nothing yet)