django-compass2 0.2

Simple compilation of Compass projects for Django.

django-compass2 is a re-usable Django application which provides an easy way of compiling your Compass or Sass 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.

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 --pre

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

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

• 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 management command:

  $ python manage.py compass

Usage

The command-line interface is very simple. To see available options and commands try:

$ python manage.py compass --help

Basically the syntax is as simple as:

$ python manage.py compass <primary_command>

Just compile your Sass into CSS:

$ python manage.py compass
   exists media/css
unchanged media/sass/style.sass

The above command is more or less equivalent to invoking:

compass --sass-dir media/sass --css-dir media/css --output-style compact

Monitor your Sass continuously:

$ python manage.py compass watch
>>> Compass is watching for changes. Press Ctrl-C to Stop.
>>> Change detected to: .../media/sass/style.sass
overwrite media/css/style.css
...

Which is something like:

compass --sass-dir media/sass --css-dir media/css --output-style compact --watch

Configuration Reference

Django Settings

These should go in your settings.py file.

Required settings

• COMPASS_INPUT: The directory where you keep your Sass/Scss 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_EXECUTABLE: Path for your compass binary. Defaults to “compass”

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

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