<!--*-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]: [compass]: ## 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 `` 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', # 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 `` 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.