Package: civet
Civet=====![alt text](http://upload.wikimedia.org/wikipedia/commons/2/28/Luwak-Katze_in_Kepahiang.jpg "Civet")(Picture credit: [Leendertz](http://en.wikipedia.org/wiki/Kopi_Luwak#mediaviewer/File:Luwak-Katze_in_Kepahiang.jpg))Civet precompiles asset files (such as Sass, CoffeeScript and ECMAScript 6) inyour Django project when you use the `runserver` command. It will also watchthe file changes for you. Therefore, you can edit your asset files and expect`runserver` to recompile those files upon save, just like it how restarts theapp server when you make changes to your Python source codeUsage-----In your `settings.py`, add Civet to your `INSTALLED_APPS` setting.In Django 1.6 and before, add it right after`django.contrib.staticfiles`. In Django 1.7 and later, add itbefore `django.contrib.staticfiles`:```pythonINSTALLED_APPS = (# ...# 'civet',  # Uncomment for Django 1.7 and later'django.contrib.staticfiles',# 'civet',  # Uncomment for Django 1.6 and earlier# ...)```Then add a `CIVET_PRECOMPILED_ASSET_DIR` setting that tells Civet where toput the precompiled assets. For example:CIVET_PRECOMPILED_ASSET_DIR = os.path.join(BASE_DIR, 'precompiled_assets')That's it. Once set up, each time you use `manage.py runserver`, Civet willfirst check to see if there are new Sass and CoffeeScript files that needprecompiling. It will also start watch for file changes.Asset Versions Supported----------------------------------------Civet is known to work with the following compilers:* Sass 3.2.5+ and Compass 0.12.2+* CoffeeScript 1.6.3+* Babel 6.3.17+"But We Only Use Sass (or CoffeeScript)"----------------------------------------You can choose which compilers Civet uses (and add your own) via a setting:```pythonCIVET_COMPILER_CLASSES = (civet.compilers.es6.ES6Compiler,)```Customizable Options--------------------By default, Civet looks for `coffee`, `sass`, and `babel` in your `PATH`environment varible. If you want to use specific paths, you can put these inyour `settings.py`:# The paths here are just examplesCIVET_COFFEE_BIN = '/opt/local/bin/coffee'CIVET_SASS_BIN = '/opt/local/bin/sass'CIVET_BABEL_BIN = '/opt/local/bin/babel'For Sass, a lot of people use [Bundler](http://bundler.io/) to manage theirRuby command-line tools. This can be especially useful if you also uselibaries like Compass and want to lock down their versions. Bundler requiresyou to set up a `Gemfile`. To use Bundler to run Sass, add this in your`settings.py`:CIVET_BUNDLE_GEMFILE = '/some/where/Gemfile'Please note that `CIVET_BUNDLE_GEMFILE` and `CIVET_SASS_BIN` must not be setat the same time. If both are set, Civet will raise an error. Also, bydefault, Civet looks for the tool `bundle` in your `PATH`. If you want touse a specific path, set `CIVET_BUNDLE_BIN` in your `settings.py`.Finally, if you want to use additional CoffeeScript or Sass compiling options,add these to your `settings.py`. Here are the default values Civet uses:CIVET_COFFEE_SCRIPT_ARGUMENTS = ('--compile', '--map')CIVET_SASS_ARGUMENTS = ()If you want to, for example, use Compass with Sass, use:CIVET_SASS_ARGUMENTS = ('--compass',)You can also define patterns (files or directories) for Civet to ignore bysetting:# As an exmaple, this will cause Civet to ignore files with 'coffee' in the# name or path.CIVET_IGNORE_PATTERNS = ['coffee']This gets extended into the ignore_patterns list defined in`django.contrib.staticfiles.management.commands.collectstatic`.You can also define staticfile directories you want Civet to ignore by setting:# This will cause Civet to ignore files located in 'bower_components' or# 'node_modules' even if those folders are included in STATICFILES_DIRS.CIVET_IGNORE_DIRS = ['bower_components', 'node_modules']This is particularly useful when using a package manager such as [Bower](http://bower.io/)or [NPM](https://www.npmjs.com/).  These managers often install packages thatinclude their own build systems, configurations, and files that are incompatiblewith how Civet compiles assets.For ES6, you can specify the NODE_PATH used for babel by setting`CIVET_ES6_NODE_PATH`.Recompile Everything--------------------To recompile everything, just quit the server, delete the entire`CIVET_PRECOMPILED_ASSET_DIR` directory, and use the `runserver` commandagain.Sample Project--------------We have included a sample project in `testsite/` to demonstrate how Civetworks with Django.Motivation----------We have developed Civet to solve the following problems:1. It is too cumbersome to ask all our developers to remember using`coffee -w` and `sass -w` every time they use `runserver`.2. We want our CoffeeScript and Sass assets to be precompiled. It makes nosense to compile them on the fly as we serve static assets. Plus, Sassfiles that have a lot of includes can take a long time to process.At one point we had a Sass file that took 6 seconds to compile. We don'twant our developers to wait for 6 seconds every time they reload a page.3. Django's static file layout requires Sass and CoffeeScript to watchfor separate directories. We simply can't have them watch the top-leveldirectory and call it a day. It is very cumbersome, however, to haveSass compiler watch multiple directories, and the option formulti-directory watch simply doesn't exist in the CoffeeScript compiler.4. We have a lot of CoffeeScript files, and on OS X that number exceeds thedefault maximum number of files that node.js (on which the officialCoffeeScript compiler is based on) can watch. (See[this issue](https://github.com/joyent/node/issues/2479) for details.)About the Name--------------Civet is "a slender nocturnal carnivorous mammal" (according to *New OxfordAmerican Dictionary*) that also produces[kopi luwak](http://en.wikipedia.org/wiki/Kopi_Luwak) by ingesting coffeebeans. I was looking for a cheeky (sassy) project name that has to do withcoffee, and this comes to mind. Disclaimer: I have no idea what kopi luwaktastes like, and no animal is harmed during the development of this plug-in.