CoffeeScript support

[ezekg]

It'd be great if the generator gave an option for CoffeeScript, similar to how it asks if you use Sass, etc. Took me awhile to get my Gruntfile and everything else set up to use it.

[pascalduez]

I'm not a huge fan of CoffeeScript myself, but I understand some people would like to use it.

Where do you intend to use it ? In you're generated theme front JS ? And would like a task to be added to Grunt/Gulp for compiling it ?

Or do you mean to also have the Gruntfile / Gulpfile written in Coffee ?

[ezekg]

I enjoy using CoffeeScript for really anything JS-related. I'd mainly like to use it for the front-end, but I even converted my Gruntfile to Coffee. I guess that just comes from my love for Ruby. I set up tasks to compile and concat my Coffee files into a single main.js file, that is then sent through Uglifier before being dumped into the docs folder. Would be great if this setup was automated for any future theme development.

[valeriangalliat]

@ezekg We didn't felt the need for CoffeeScript in the team, but I understand you'd like to use CoffeeScript in a SassDoc theme. Have you already updated your theme to use it?

If so, it would be awesome if you can show us your work, so we can integrate it (maybe with some tweaks to make it more generic) in a new option for the generator!

[pascalduez]

Here's the plan:

We will add a new CoffeeScript option/task for the Gruntfile and Gulpfile. This will care of the front-end files: assets/coffee/**/*.coffee --> assets/js/main.js
Those files are already into some rework and many other options/tasks being added, so no big deal.
See #15

About the option to have the Gruntfile or Gulpfile into coffee. We'll consider it. Not a priority though.
Feels odd to me to have some coffee compiled to setup task to have some coffee compiled... :)
Plus this adds a significant overload on maintaining those files: 4 instead of 2.

We could even extend things to have the theme index.coffee.
But once again, introduce maintenance overload.

[ezekg]

Having the Gruntfile in CoffeeScript isn't a big deal, as it only takes a min or so to convert.

Here's my package.json,

{
  "name": "flint-docs",
  "description": "Docs for Flint",
  "version": "0.1.0",
  "keywords": [
    "sassdoctheme"
  ],
  "dependencies": {
    "extend": "^1.0.0",
    "sassdoc-filter": "^1.0.0",
    "sassdoc-indexer": "^1.0.0",
    "swig": "^1.4.2",
    "themeleon": "^1.0.0",
    "themeleon-swig": "^1.0.2"
  },
  "engines": {
    "node": ">=0.10.0"
  },
  "devDependencies": {
    "chalk": "^0.5.1",
    "fs-extra": "^0.12.0",
    "grunt": "^0.4.5",
    "grunt-autoprefixer": "^1.0.1",
    "grunt-browser-sync": "^1.5.2",
    "grunt-contrib-coffee": "^0.11.1",
    "grunt-contrib-concat": "^0.5.0",
    "grunt-contrib-sass": "^0.8.1",
    "grunt-contrib-uglify": "^0.6.0",
    "grunt-contrib-watch": "^0.6.1",
    "load-grunt-tasks": "^0.6.0",
    "q": "^1.0.1",
    "sassdoc": "^1.8.0",
    "time-grunt": "^1.0.0"
  }
}

And my Gruntfile,

"use strict"
path = require("path")
fs = require("fs")
fse = require("fs-extra")
chalk = require("chalk")
Q = require("q")
sassdoc = require("sassdoc")
copy = Q.denodeify(fse.copy)

# Set your Sass project (the one you're generating docs for) path.
# Relative to this Gruntfile.
projectPath = "../"

# Project path helper.
project = ->
    args = Array::slice.call(arguments)
    args.unshift projectPath
    path.resolve.apply path, args

# Project specific paths.
dirs =
    scss: "src/sass"
    coffee: "src/coffee"
    css: "assets/css"
    js: "assets/js"
    tpl: "views"
    src: project("sass")
    docs: project("docs")

# Tasks configs.
config =

    dirs: dirs

    sass:
        options:
            style: "compressed"

        develop:
            files: [
                expand: true
                cwd: "<%= dirs.scss %>"
                src: ["*.scss"]
                dest: "<%= dirs.css %>"
                ext: ".css"
            ]

    coffee:
        compile:
            files: [
                expand: true
                cwd: "<%= dirs.coffee %>"
                src: ["*.coffee"]
                dest: "<%= dirs.js %>"
                ext: ".js"
            ]

    watch:
        scss:
            files: ["<%= dirs.scss %>/**/*.scss"]
            tasks: [
                "sass:develop"
                "dumpCSS"
            ]

        coffee:
            files: ["<%= dirs.coffee %>/**/*.coffee"]
            tasks: ["coffee:compile"]

        js:
            files: ["<%= dirs.js %>/**/*.js"]
            tasks: [
                "concat"
                "uglify"
                "dumpJS"
            ]

        tpl:
            files: ["<%= dirs.tpl %>/**/*.swig"]
            tasks: ["compile:develop"]

    concat:
        options:
            separator: ";"
        dist:
            src: ["<%= dirs.js %>/test.js"]
            dest: "<%= dirs.js %>/main.js"

    uglify:
        options: {}
        develop:
            files:
                "<%= dirs.js %>/main.min.js": ["<%= dirs.js %>/main.js"]

    # SassDoc compilation (documentize).
    # See: https://github.com/SassDoc/sassdoc/wiki/Customising-the-View
    compile:
        options:
            verbose: true
            theme: "."

        # basePath: '',
        # package: project('package.json'),
        # groups: {
        #   'undefined': 'General'
        # }
        develop:
            src: "<%= dirs.src %>"
            dest: "<%= dirs.docs %>"

module.exports = (grunt) ->

    # Load all grunt tasks matching the `grunt-*` pattern.
    require("load-grunt-tasks") grunt

    # Time how long tasks take.
    require("time-grunt") grunt
    grunt.initConfig config

    # A custom task to compile through SassDoc API.
    grunt.registerMultiTask "compile", "Generates documentation", ->
        done = @async()
        config = @options({})

        # Enable verbose.
        sassdoc.logger.enabled = config["verbose"]
        src = @filesSrc[0]
        dest = @files[0].dest
        sassdoc.documentize(src, dest, config).then done
        return

    # Dump js files from theme into `docs/assets` whenever they get modified.
    # Prevent requiring a full `compile`.
    grunt.registerTask "dumpJS", "Dump JS to docs/assets", ->
        done = @async()
        src = dirs.js
        dest = path.join(dirs.docs, "assets/js")
        copy(src, dest).then ->
            grunt.log.writeln "JS " + chalk.cyan(src) + " copied to " + chalk.cyan(dest) + "."
            done()
            return

        return

    # Dump CSS files from theme into `docs/assets` whenever they get modified.
    # Prevent requiring a full `compile`.
    grunt.registerTask "dumpCSS", "Dump CSS to docs/assets", ->
        done = @async()
        src = dirs.css
        dest = path.join(dirs.docs, "assets/css")
        copy(src, dest).then ->
            grunt.log.writeln "CSS " + chalk.cyan(src) + " copied to " + chalk.cyan(dest) + "."
            done()
            return

        return

    # Development task.
    # While working on a theme.
    grunt.registerTask "develop", "Development task", ->
        tasks = [
            "browserSync:develop"
            "watch"
        ]
        docs = fs.existsSync(dirs.docs)
        unless docs
            grunt.log.writeln "Running initial compile: " + chalk.cyan(dirs.docs) + "."
            tasks.unshift "compile:develop"
        grunt.task.run tasks
        return

    return