Source

django-compass2 / README

Full commit
==================
django-compass2
==================

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

.. _Compass: http://compass-style.org/
.. _Sass:    http://sass-lang.com


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.