======
Minify
======

Minify provides setuptools commands for minifying CSS and JS resources using the
well-known `YUI compressor`_ from Yahoo! Inc. When you install ``minify``, two
new commands are available:

- ``minify_js`` which minifies Javascript files
- ``minify_css`` which minifies CSS files

See the Usage_ section for more information about these commands.


.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/


Installation
============

The Minify commands are meant to be used in an existing python project. So, in
order to make the commands available in your project, just add ``minify`` to
the requirements of your project, for example::

    setup(
        ...
        install_requires=['minify'],
        ...
    )

Then, when you install your package with setuptools or something equivalent (for
example with ``python setup.py develop``), the minify commands will be available.

Also, since the YUI compressor tool is written in Java, you should have a Java
virtual machine installed on your system and available in your system ``PATH``.


Usage
=====

.. _Usage:


Minify provides two commands for minifying CSS and JS resources:

- ``minify_js`` which minifies Javascript files
- ``minify_css`` which minifies CSS files


Minifying Javascript files
--------------------------

To show the options of the ``minify_js`` command, just type::

    $ python setup.py minify_js --help


You should obtain something like this::

    Common commands: (see '--help-commands' for more)
    
      setup.py build      will build the package underneath 'build/'
      setup.py install    will install the package
    
    Global options:
      --verbose (-v)  run verbosely (default)
      --quiet (-q)    run quietly (turns verbosity off)
      --dry-run (-n)  don't actually do anything
      --help (-h)     show detailed help message
      --no-user-cfg   ignore pydistutils.cfg in your home directory
    
    Options for 'minify_js' command:
      --sources                sources files
      --output                 minified output filename. If you provide a template
                               output filename (e.g. "static/%s-min.ext"), the
                               source files will be minified individually
      --charset                Read the input file(s) using <charset>
      --line-break             Insert a line break after the specified column
                               number
      --nomunge                Minify only, do not obfuscate
      --preserve-semi          Preserve all semicolons
      --disable-optimizations  Disable all micro optimizations
    
    usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
       or: setup.py --help [cmd1 cmd2 ...]
       or: setup.py --help-commands
       or: setup.py cmd --help

The ``minify_js`` tool can be used on the command-line. Here is an example::

    $ python setup.py minify_js --sources static/*.js --output static/combined.js


But, the most useful way to use ``minify_js`` is via a ``setup.cfg`` file
located in your project root directory (that is, next to the ``setup.py``
file)::

    [minify_js]
    sources = static/one.js static/two.js
    output = static/combined.js
    nomunge = yes

Then, we you run the ``minify_js`` command, the command options will be read
from the ``setup.cfg`` file in addition to the command-line arguments.

Note that, since there's a single output file for many sources, the
sources files are merged into a single file which is compressed with the YUI
compressor in order to produce a single minified file.

However, you may want to compress the sources files individually and obtain
distinct minified files. In that case, you should provide a template output
filename instead of a regular output filename. A template output filename is a
filename with a ``%s`` in it, which will be substitued by the current source
name being processed. For example::

    [minify_js]
    sources = static/one.js static/two.js
    output = static/%s-min.js

Running ``python setup.py minify_js`` will then produce two minified files:
``static/one-min.js`` and ``static/two-min.js``.


Minifying CSS files
-------------------

You can also see the options of the ``minify_css`` command, by typing::

    $ python setup.py minify_css --help

And here is the result::

    Common commands: (see '--help-commands' for more)
    
      setup.py build      will build the package underneath 'build/'
      setup.py install    will install the package
    
    Global options:
      --verbose (-v)  run verbosely (default)
      --quiet (-q)    run quietly (turns verbosity off)
      --dry-run (-n)  don't actually do anything
      --help (-h)     show detailed help message
      --no-user-cfg   ignore pydistutils.cfg in your home directory
    
    Options for 'minify_css' command:
      --sources     sources files
      --output      minified output filename. If you provide a template output
                    filename (e.g. "static/%s-min.ext"), the source files will be
                    minified individually
      --charset     Read the input file(s) using <charset>
      --line-break  Insert a line break after the specified column number
    
    usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
       or: setup.py --help [cmd1 cmd2 ...]
       or: setup.py --help-commands
       or: setup.py cmd --help

This command can be used about the same way as the ``minify_js`` command, but
it has less options.


Combining minification operations
---------------------------------

You can also combine minification operations thanks to the builtin ``alias``
command (still specified in the ``setup.cfg`` file)::

    [alias]
    minify_each_css = minify_css --sources static/*.css --output static/%s-min.css --charset utf-8
    minify_each_js = minify_js --sources static/*.js --output static/%s-min.js --charset utf-8
    minify_each = minify_each_css minify_each_js

Then call ``minify_each`` by typing:: 
    
    $ python setup.py minify_each


Support
=======

This project is hosted on `bitbucket.org
<https://bitbucket.org/sprat/minify/>`__.
Please report issues via the bug tracker.
