Overview

<!---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.