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
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
These should go in your settings.py file.
- 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.
- 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_RELATIVE_URLS: Boolean specifying whether or not Compass's asset URL helpers should generate relative URLs.
These options may be passed at runtime to affect how Compass is run.
- -t, --trace: Print a full stacktrace on Compass errors.