Skip to content

D
django-pipeline
Commit bb7acd43 by Timothée Peignier
Options

removing from docs what has been removed from code

parent e1e4f2f1
Showing with 0 additions and 226 deletions
docs/configuration.rst
......@@ -126,60 +126,6 @@ Other settings
Defaults to ``not DEBUG`` (compressed files will only be used when ``DEBUG`` is ``False``).
``PIPELINE_AUTO``
.................
Auto-generate CSS and JavaScript files whenever needed, when the template tags
are invoked.
This setting will make sure that the outputted files always are up to date
(assuming that you are using the provided templatetags to output the links to
your files).
If you disable this, you can use the management command to keep your files
manually updated.
Defaults to ``True``.
``PIPELINE_VERSION``
....................
Regulates whether or not to add a "version number" to the outputted files
filename with for use with “far future Expires”.
When you specify ``PIPELINE_VERSION`` you will also need to add a placeholder
(which by default is ``?``) for the version number in the ``output_filename`` setting.
``PIPELINE_VERSION_REMOVE_OLD``
...............................
When ``True``, old compressed files will be removed when new versions are generated.
All files with a matching name e.g. ``output_filename`` where ``?`` can be replaced
by digits will be removed.
If you for some reason have files named in the same way, you should consider moving
them or putting the compressed files in their own directory.
Defaults to ``True``.
Example::
PIPELINE = True
PIPELINE_VERSION = True
PIPELINE_CSS = {
'screen': {
'source_filenames': (
'css/screen/style.css', 'css/screen/paginator.css',
'css/screen/agenda.css', 'css/screen/weather.css',
'css/screen/gallery.css',
),
'output_filename': 'c/screen.r?.css',
},
}
This will output a file like ``/media/c/screen.r1213947531.css``,
which will be re-generated and updated when you change your source files.
``PIPELINE_CSS_COMPRESSOR``
............................
......@@ -229,13 +175,6 @@ Other settings
Defaults to ``"_.template"``
``PIPELINE_CACHE_TIMEOUT``
..........................
Package version are cached to avoid unnecessary IO, the default is to cache
version for 2 years.
Defaults to ``63072000``
Embedding fonts and images
==========================
......@@ -292,56 +231,3 @@ In resulting CSS it will be rewritten to ::
background-image:url(/js/fancybox/fancybox-y.png);
(Assuming ``PIPELINE_URL`` is '' or '/', with non-empty ``PIPELINE_URL`` result will be another).
External urls
=============
.. warning::
This feature is currently deprecated and will be remove in next major version of pipeline.
While Pipeline does a great job of minimizing the amount of http requests
on your site (hence increasing performance) there are sometimes cases when you
want to include external files as well. Let's take an example::
PIPELINE_JS = {
'jquery': {
'external_urls': (
'http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js',
'http://ajax.googleapis.com/ajax/libs/jqueryui/1.5.2/jquery-ui.min.js'
),
},
'all': {
'source_filenames': ('js/blog.js', 'js/comments.js'),
'output_filename': 'js/all.js',
},
}
In template::
{% load compressed %}
{% compressed_js 'jquery' %}
{% compressed_js 'all' %}
Output in when ``settings.PIPELINE = False``::
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js" charset="utf-8"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.5.2/jquery-ui.min.js" charset="utf-8"></script>
<script type="text/javascript" src="/media/js/blog.js" charset="utf-8"></script>
<script type="text/javascript" src="/media/js/comments.js" charset="utf-8"></script>
Output in when ``settings.PIPELINE = True``::
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js" charset="utf-8"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.5.2/jquery-ui.min.js" charset="utf-8"></script>
<script type="text/javascript" src="/media/js/all.js" charset="utf-8"></script>
Now why is this good you ask? The more script sources the more impact on performance
according to http://developer.yahoo.com/performance/rules.html#num_http
which is true but if you are low bandwidth or superbig you may want to offload
some horsepower to google which leads us as hinted in the example above to the next topic.
.. note::
External urls is currently only available for javascript.
docs/index.rst
......@@ -18,7 +18,6 @@ Table Of Contents
usage
compressors
compilers
versioning
templates
storages
signals
......
docs/versioning.rst deleted 100644 → 0
.. _ref-versioning:
==========
Versioning
==========
.. warning::
This feature is currently deprecated and will be remove in next major version of pipeline.
There are several ways for generating version strings. Basically, three types are available.
These are:
* `mtime <#modification-time-version>`_
* `hash <#hash-version>`_
* `git <#git-version>`_
Modification time version
=========================
This is the default method for generating version strings. In short, when invoked, it checks whether any of the source files system timestamps (mtime) is newer than the version string of the corresponding compressed file. If that is the case, the compressed output file version string will be the mtime of the most recent source file.
Hash version
============
Hash-based versioning works by generating a hash string based on the contents of the source files. Available hash-based versioning methods are MD5 and SHA-1.
MD5 version
-----------
To generate MD5 version strings, put this in your `settings.py` ::
PIPELINE_VERSIONING = 'pipeline.versioning.hash.MD5Versioning'
SHA-1 version
-------------
To generate SHA-1 version strings, put this in your `settings.py`::
PIPELINE_VERSIONING = 'pipeline.versioning.hash.SHA1Versioning'
Git version
===========
Versions formed on git revisions in codebase. Provides a fast way to check if any of your files changed that
will be consistent across multiple web servers so that they all generate the same version numbers for each
set of source files, assuming their git repositories are all in sync.
Assumes deployment is git repositiory. Requires GitPython 0.2.0.
GitPython 0.3.0 uses an async library that does not currently play well with Django. To install using Git just do
pip install GitPython==0.2.0-beta1.
Git revision version
--------------------
To generate versions based on revision of every file in your source file list, put this in your `settings.py`::
PIPELINE_VERSIONING = 'pipeline.versioning.git.GitVersioningBase'
Git HEAD last revision version
------------------------------
To generate versions based on the latest revision of HEAD in your git repository (which assumes all of your source files are in the
same repository), put this in your `settings.py`::
PIPELINE_VERSIONING = 'pipeline.versioning.git.GitHeadRevVersioning'
Write your own versioning class
===============================
To write your own versioning class, you can subclass one of the available versioning classes.
Example
-------
For example, you want a short version string based on the SHA-1 version string.
You can do this by subclassing the SHA1Versioning class and overriding its get_version() method, like this::
from pipeline.versioning.hash import SHA1Versioning
class ShortSHA1Versioning(SHA1Versioning):
"""Custom SHA1Versioning class"""
def get_version(self, source_files):
"""Return the first 10 characters of the SHA-1 version string"""
version = super(ShortSHA1Versioning, self).get_version(source_files)
return version[:10]
In your ``settings.py`` add::
PIPELINE_VERSIONING = 'app.module.ShortSHA1Versioning'
.. note::
Replace ``app`` and ``module`` by the app and module that contains your versioning class
Production environment
======================
You probably do not want the source files to be evaluated and (if needed)
regenerated on every request in a production environment.
Especially when calculating a hash on every request could be expensive.
To avoid this, make sure your source files are compressed before deployment,
and put the following settings in your production environment's ``settings.py``::
PIPELINE_AUTO = False
PIPELINE_VERSION = True
This way, the names of the compressed files will be looked up in the file system, instead of being evaluated and (if needed) regenerated on every request.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment