documented-style-sheets / grunt-dss

:book: grunt-dss is a Grunt plugin that builds documentation based on the the DSS parser

Grunt-DSS

Grunt-DSS is a Grunt plugin that generates UI documentation from CSS, Less, Stylus, Sass files based on the DSS parser output.

Getting Started

This plugin requires Grunt ~0.4.0

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-dss --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-dss');

In your project's Gruntfile, add a section named dss to the data object passed into grunt.initConfig().

Settings

files

Type: Array or Object Default value: []

Files to parse. Using Grunt default files syntax. More about that on Gruntjs wiki.

options.template

Type: String Default value: {task_path}/template/

A relative path to a mustache template to be used instead of the default.

options.template_index

Type: String Default value: index.handlebars

The filename of the index of the template.

options.output_index

Type: String Default value: index.html

The filename of the index for the output file.

options.parsers

Type: Object Default value: {}

An object filled with key value pairs of functions to be used when parsing comment blocks. See the example below for more context about how to use these.

options.include_empty_files

Type: Boolean Default value: true

Include files without DSS annotations.

Example initConfig

grunt.initConfig({
  dss: {
    docs: {
      files: {
        'api/': 'css/**/*.{css,scss,sass,less,styl}'
      },
      options: {
        template: '/dark_theme/',
        parsers: {
          // Finds @link in comment blocks
          link: function(i, line, block){

            // Replace link with HTML wrapped version
            var exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
            line.replace(exp, "<a href='$1'>$1</a>");
            return line;
          }
        }
      }
    }
  }
});

DSS Sublime Text Plugin

You can now auto-complete DSS-style comment blocks using @sc8696's Auto-Comments Sublime Text Plugin

grunt-dss's Issues

Add option to pass css file to the default template

It would be great to have a option to pass a additional css to actually get the styles in the styleguide without having to duplicate default template.

Travis CI errors

I keep getting build errors sent to my email when there doesn't seem to be an issue. I've also noticed (in the last 48 hours) that the image/statues fluctuates from build:error and build:passing. That said, my last PR was passing before I merged. What's going on? Are the tests being run all the time and somehow fail every once in awhile?

Mustache files are included in generated docs

Right now the DSS clones the template directory verbatom. This means .mustache files are included in the output directory along with the .html files. Since they are sort of useless at that point, it would be better to remove them from the cloning process.

Multiline markup

I see that DSS has been edited to use multiline markup examples. Can we get that change integrated into grunt-dss as well?

All in all, this is a great tool.

Styleguide is generated but without any style

Hi ! :)
I have a question about how to use this grunt plugin : when i generated the styleguide, everything work but there is no style applied to.
In the less file :

//
// @name Button
// @description Your standard form button.
//
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// @state .primary - Indicates button is the primary action.
// @state .smaller - A smaller button
//
// @markup
// <button>This is a button</button>
//
button {
  padding: 5px 15px;
  line-height: normal;
  font-family: "Helvetica Neue", Helvetica;
  font-size: 12px;
  font-weight: bold;
  color: #666;
  text-shadow: 0 1px rgba(255, 255, 255, 0.9);
  border-radius: 3px;
  border: 1px solid #ddd;
  border-bottom-color: #bbb;
  background: #f5f5f5;
  filter: progid:DXImageTransform.Microsoft.gradient(GradientType=0, startColorstr='$start', endColorstr='$end');
  background: -webkit-gradient(linear, left top, left bottom, from(#f5f5f5), to(#e5e5e5));
  background: -moz-linear-gradient(top, #f5f5f5, #e5e5e5);
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.15);
  cursor: pointer;
}

My grunt task whas :

dss: {
    docs: {
        files: {
            '<%= meta.filesRoute.doc %>/styleguide/dist/': ['<%= meta.filesRoute.less %>/base.less']
        }
    }
}

and the result in the console :

Running "dss:docs" (dss) task
✓ Styleguide overwrited at: src/Bundle/FrontendBundle/Resources/doc/styleguide/dist/

Done, without errors.

But result styleguide :

Thanks for your help !

ENOENT in certain cases when output directory does not exist

Sample Gruntfile:

  grunt.initConfig
    dss:
      docs:
        files:
          "docs/build/css/": "views/**/*.{css,scss,sass,less,styl}"

If the docs/ folder exists, but docs/build/ does not, Grunt will fail with:

Warning: ENOENT, no such file or directory 'docs/build/css/' Use --force to continue.

However, the following case works (as before, docs/ exists):

  grunt.initConfig
    dss:
      docs:
        files:
          "docs/build-css/": "views/**/*.{css,scss,sass,less,styl}"

(The difference being that, in the working case, we are writing to a non-existant folder that is an immediate descendant of an existing folder.)

Is all prettify languages required in default template ?

Maybe something like prismjs can be lighter for html & css ?

Error when template is not found

There's a little bug in line 88 when a template is not found.

The issue is you're calling grunt.fail(...) but it should be grunt.fail.fatal(...) or grunt.fatal(...).

Thank you for your work on DSS!

How to add state (class and pseudo-class) to markup.example ?

I think with custom parser for markup and template ? But after some research and testing I have not found a good solution ...

Thanks for any help :)

edit and it's probably a side effect of #15 ?

Update default template to something lighter

What do you think about having a lighter template that use BEM approch to scope styles correctly ?

Avoid reset, & default styles (with tag) and add a dss-Styleguide prefix on all className of items ?

Look what my template look like right now:

This seems to bloat the code, but it can avoid having conflict with default styles of the styleguide default styles.
What do you think ?

How state markup works ?

I run the example & get this:

Is it a bug ? Are the examples up to date ?