<!--*-markdown-*-->

# `django-compass`

`django-compass` is a re-usable Django application which provides an easy way of
compiling your [Compass/Sass][compass]-based stylesheets to CSS. Its main
benefit is Django settings integration, so you don’t need lots of `compass.rb`
configuration files lying around (especially with multiple deployments, et
cetera). Other than that, it’s simply a proxy to the `compass` command-line
application.

  [django-boss]: http://bitbucket.org/zacharyvoase/django-boss/
  [compass]: http://compass-style.org/


## Installation and Setup

*   You’ll need to install [Compass][]; this is a Ruby library, so use the `gem`
    utility (installed out-of-the-box on most systems):

        $ [sudo] gem install compass

*   Then, just use `pip` or `easy_install` to install `django-compass` (the
    dependencies will be handled automatically):

        $ pip install django-compass # OR
        $ easy_install django-compass

*   Add `'djcompass'` to your `INSTALLED_APPS` setting.

*   In your `settings.py` file, add the necessary settings. Take a look at the
    configuration reference below for more information, but here’s a quick
    example:
    
        COMPASS_INPUT = PROJECT_ROOT + 'media/sass'
        COMPASS_OUTPUT = PROJECT_ROOT + 'media/css'
        COMPASS_STYLE = 'compact'
        COMPASS_REQUIRES = (
            'ninesixty',  # 960.gs Grid System
        )

*   You can now compile your Sass with the `djboss` command:

        $ djboss compass


## Usage

`django-compass` uses [django-boss][], a library/tool for writing and running
Django management commands. This will be installed automatically by setuptools
when you install `django-compass`.

The command-line interface is very simple:

    $ djboss compass --help
    usage: djboss compass [-h] [-w] [-d] [-t]
    
    Compile Sass stylesheets using Compass.
    
    optional arguments:
      -h, --help     show this help message and exit
      -w, --watch    Monitor the source directory, rebuilding the CSS when Sass
                     changes
      -t, --trace    Print a full Ruby stacktrace on errors.

Just compile your Sass into CSS:

    $ djboss compass
    compass --sass-dir media/sass --css-dir media/css --output-style compact
       exists media/css
    unchanged media/sass/style.sass

Monitor your Sass continuously:

    $ djboss compass -w
    compass --sass-dir media/sass --css-dir media/css --output-style compact --watch
    >>> Compass is watching for changes. Press Ctrl-C to Stop.
    >>> Change detected to: .../media/sass/style.sass
    overwrite media/css/style.css
    ...


## Configuration Reference

### Django Settings

These should go in your `settings.py` file.


#### Required settings

*   `COMPASS_INPUT`: The directory where you keep your Sass stylesheets.

*   `COMPASS_OUTPUT`: The directory to which Compass should output CSS.

Note that neither of these should have trailing slashes. They may be absolute or
relative paths; if relative, they will be resolved against the current working
directory.


#### Optional settings

*   `COMPASS_STYLE`: One of `'nested'`, `'expanded'`, `'compact'` or
    `'compressed'`, specifying the style of the produced CSS output. The default
    is `'compact'`.

*   `COMPASS_REQUIRES`: A sequence of Ruby libraries to `require` before running
    Compass commands.

*   `COMPASS_IMAGE_DIR`: The directory where images are stored (used for
    Compass’s asset URL helpers).

*   `COMPASS_SCRIPT_DIR`: The directory containing your JavaScript files (used
    for Compass’s asset URL helpers).

*   `COMPASS_RELATIVE_URLS`: Boolean specifying whether or not Compass’s asset
    URL helpers should generate relative URLs.


### Command-line Options

These options may be passed at runtime to affect how Compass is run.

*   `-w`, `--watch`: Monitor the Sass source directory, and update the CSS build
    every time a file is changed. This is a long-running process, which you can
    stop with the usual Ctrl-C.

*   `-t`, `--trace`: Print a full stacktrace on Compass errors.
