grunt-docless

grunt-docless

CSS documentation generator with less effort.

Getting Started

This plugin requires Grunt.

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

Note: ensure you have git installed before installing grunt-docless

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

grunt.loadNpmTasks('grunt-docless');

The "docless" task

Overview

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

The staticDirs object should contain locations of any media directories you need to be copied into the documentation directory such as fonts or images.

grunt.initConfig({
  docless: {
      documentation: {
        files: {
          "styles/build/styles.min.css": ["styles/src/*.less", "styles/src/module/*.less"]
        }
      },
      options: {
        title: 'Docless Example CSS Documentation',
        doc_path: 'docs',
        staticDirs: [{
          src_path: 'img',
          dest_path: 'docs/img'
        },
        {
          src_path: 'font',
          dest_path: 'docs/font'
        }]
      }
    },
})

Documenting your CSS

Docless is inspired by YUIDoc and uses syntax you will be familiar with.

HTML snippets are generated by docless using Emmet ( ZenCoding ) style syntax prefixed by @usage. Each documentation block can contain multiple lines of comments and multiple @usage blocks.

See example of a css declaration block documented with docless:

/**
Generic List
This is a generic list class

@usage ul.list-generic>li*5>lorem4
**/
ul.list-generic {
  ...
}

Viewing the documentation

Docless will generate an output directory which you can specify with the doc_path property on the options object. By default it will create a new docs folder in the current directory.

You can then spin up a static server in the docs directory to view the documentation.

Release History

• 2013-12-01 v0.1.5 fixed issue with paths not being correctly resolved, added staticDirs
• 2013-11-17 v0.1.4 rewrite of docless, updated readme.

License

Copyright (c) 2013 Ray Gerrard. Licensed under the MIT license.