docs cleanup (fixes #127)

Author: stefanfoulis

README.rst

@@ -12,7 +12,7 @@ Wiki: https://github.com/stefanfoulis/django-filer/wiki
 Dependencies
 ------------
 
-* `Django`_ 1.2 with django-staticfiles or `Django`_ 1.3
+* `Django`_ >= 1.3 (with ``django.contrib.staticfiles``)
 * django-mptt >= 0.2.1
 * `easy_thumbnails`_ >= 1.0-alpha-17
 * `django-polymorphic`_ >= 0.2
@@ -33,18 +33,11 @@ Configuration
 Add ``"filer"`` and ``"easy_thumbnails"`` to your project's ``INSTALLED_APPS`` setting and run ``syncdb``
 (or ``migrate`` if you're using South).
 
-For automatic subject location aware cropping of images replace 
-``easy_thumbnails.processors.scale_and_crop`` with
-``filer.thumbnail_processors.scale_and_crop_with_subject_location`` in the
-``THUMBNAIL_PROCESSORS`` setting::
+See the docs for advanced configuration:
 
-    THUMBNAIL_PROCESSORS = (
-        'easy_thumbnails.processors.colorspace',
-        'easy_thumbnails.processors.autocrop',
-        #'easy_thumbnails.processors.scale_and_crop',
-        'filer.thumbnail_processors.scale_and_crop_with_subject_location',
-        'easy_thumbnails.processors.filters',
-    )
+  * `subject location docs`_
+  * `permission docs`_ (experimental)
+  * `secure file downloads docs`_ (experimental)
 
 
 .. _Django: http://djangoproject.com
@@ -53,3 +46,7 @@ For automatic subject location aware cropping of images replace
 .. _sorl.thumbnail: http://thumbnail.sorl.net/
 .. _PIL: http://www.pythonware.com/products/pil/
 .. _Pillow: http://pypi.python.org/pypi/Pillow/
+.. _docs: http://django-filer.readthedocs.org/en/latest/index.html
+.. _subject location docs: http://django-filer.readthedocs.org/en/latest/installation.html#subject-location-aware-cropping
+.. _permission docs: http://django-filer.readthedocs.org/en/latest/permissions.html
+.. _secure file downloads docs: http://django-filer.readthedocs.org/en/latest/secure_downloads.html

docs/index.rst

@@ -56,7 +56,7 @@ Contents
    installation
    usage
    permissions
-   server
+   secure_downloads
    settings
    extending_filer
    running_tests

docs/installation.rst

@@ -11,7 +11,9 @@ The easiest way to get ``django-filer`` is simply install it with `pip`_::
     $ pip install django-filer
 
 If you are feeling adventurous you can get 
-`the latest sourcecode from github <https://github.com/stefanfoulis/django-filer/>`_
+`the latest sourcecode from github <https://github.com/stefanfoulis/django-filer/>`_ or add
+http://stefanfoulis.github.com/django-filer/unstable_releases/ to ``find-links`` for the latest
+alpha and beta releases.
 
 Dependencies
 ------------
@@ -42,16 +44,10 @@ Static media
 ............
 
 In order to operate properly, django-filer needs some js and css files. They
-are located in the ``static/filer`` directory in the ``filer`` package. If you are 
-already using `django-staticfiles`_ or `django.contrib.staticfiles`_ you're 
-already set.
+are located in the ``static/filer`` directory in the ``filer`` package. Use
+`django.contrib.staticfiles`_  (or `django-staticfiles`_) to have them
+automatically included.
 
-permissions on files
-....................
-
-.. WARNING:: File download permissions are an experimental feature. The api may change at any time.
-
-See :ref:`permissions` section.
 
 subject location aware cropping
 ...............................
@@ -80,6 +76,19 @@ To crop an image and respect the subject location::
     {% load thumbnail %}
     {% thumbnail obj.img 200x300 crop upscale subject_location=obj.img.subject_location %}
 
+permissions
+...........
+
+.. WARNING:: File permissions are an experimental feature. The api may change at any time.
+
+See :ref:`permissions` section.
+
+secure downloads
+................
+
+.. WARNING:: File download permissions are an experimental feature. The api may change at any time.
+
+See :ref:`secure_downloads` section.
 
 debugging and logging
 .....................

docs/permissions.rst

@@ -5,40 +5,15 @@ Permissions
 
 .. WARNING:: File download permissions are an experimental feature. The api may change at any time.
 
-.. NOTE:: For the impatient:
-          
-          * set ``FILER_ENABLE_PERMISSIONS`` to ``True``
-          * include ``filer.server.urls`` in the root ``urls.py`` without a 
-            prefix
-
-By default files with permissions are served directly by the `Django`_ process. That is
-acceptable in a development environment, but is very bad for performance and security in
-production. See the :ref:`file permission docs <server>` on how to serve files more efficiently
-and how use custom storage backends.
-
 By default files can be uploaded and managed by all staff members based on the
 standard django model permissions.
-Since the public files get uploaded to ``MEDIA_ROOT`` they can be downloaded by
-everyone.
 
 Activating permission checking with the ``FILER_ENABLE_PERMISSIONS`` setting enables
-permission checking on downloads. This allows setting access rights for
-editing files in the backend (with the ``edit`` permission) and downloading the
-files (with the ``read`` permission).
-For images the permissions also extend to all generated thumbnails.
-
-To be able to check permissions on the file downloads, a special view is used.
-The files are saved in a separate location outside of ``MEDIA_ROOT`` to prevent
-accidental serving. By default this is a directory called ``smedia`` that is
-located in the parent directory of ``MEDIA_ROOT``.
-The smedia directory must **NOT** be served by the webserver directly, because
-that would bypass the permission checks.
-
-To hook up the view ``filer.server.urls`` needs to be included in the root
-``urls.py``::
+fine grained permissions based on individual folders.
+Permissions can be set in the "Folder permissions" section in Django admin.
 
-    urlpatterns += patterns('',
-        url(r'^', include('filer.server.urls')),
-    )
+.. NOTE:: These permissions only concern editing files and folders in Django admin. All the files are
+          still world downloadable by anyone who guesses the url. For real permission checks on downloads
+          see the :ref:`secure_downloads` section.
 
 .. _Django: http://djangoproject.com

docs/server.rst renamed to docs/secure_downloads.rst

@@ -1,14 +1,46 @@
-.. _server:
+.. _secure_downloads:
 
-File Server Backends
-====================
+Secure Downloads
+================
 
-.. note:: Please follow the instructions for setting up :ref:`permissions` first.
-
-.. warning:: Server Backends are experimental and the API may change at any time.
+.. warning:: Secure downloads are experimental and the API may change at any time.
 
 .. warning:: Server Backends currently only work with files in the local filesystem.
 
+.. note:: For the impatient:
+
+          * set ``FILER_ENABLE_PERMISSIONS`` to ``True``
+          * include ``filer.server.urls`` in the root ``urls.py`` without a
+            prefix
+
+To be able to check permissions on the file downloads, a special view is used.
+The files are saved in a separate location outside of ``MEDIA_ROOT`` to prevent
+accidental serving. By default this is a directory called ``smedia`` that is
+located in the parent directory of ``MEDIA_ROOT``.
+The smedia directory must **NOT** be served by the webserver directly, because
+that would bypass the permission checks.
+
+To hook up the view ``filer.server.urls`` needs to be included in the root
+``urls.py``::
+
+    urlpatterns += patterns('',
+        url(r'^', include('filer.server.urls')),
+    )
+
+Files with restricted permissions need to be placed in a secure storage backend.
+Configure a secure storage backedn in :ref:`FILER_STORAGES` or use the default.
+
+.. warning:: The "Permissions disabled" checkbox in the file detail view in Django admin
+             controls in which storage backend the file is saved. In order for it to be
+             protected, this field must not be checked.
+
+For images the permissions also extend to all generated thumbnails.
+
+By default files with permissions are served directly by the `Django`_ process (using the
+``filer.server.backends.default.DefaultServer`` backend). That is
+acceptable in a development environment, but is very bad for performance and security in
+production.
+
 The private file view will serve the permission-checked media files by
 delegating to one of its server backends. The ones bundled with django-filer
 live in ``filer.server.backends`` and it is easy to create new ones.
@@ -51,7 +83,7 @@ in ``settings.py``::
 ``nginx_location`` is the location directive where nginx "hides"
 permission-checked files from general access. A fitting nginx configuration
 might look something like this::
-    
+
     location /nginx_filer_private/ {
       internal;
       alias /path/to/smedia/filer_private/;
@@ -66,9 +98,9 @@ might look something like this::
    ``alias`` vs. ``root`` have subtle differences that can make your config
    fail.
 
-``NginxXAccelRedirectServer`` will add the a ``X-Accel-Redirect`` header to 
-the response instead of actually loading and delivering the file itself. The 
-value in the header will be something like 
+``NginxXAccelRedirectServer`` will add the a ``X-Accel-Redirect`` header to
+the response instead of actually loading and delivering the file itself. The
+value in the header will be something like
 ``/nginx_filer_private/2011/03/04/myfile.pdf``. Nginx picks this up and does
 the actual file delivery while the django backend is free to do other stuff
 again.
@@ -86,7 +118,7 @@ Once you have ``mod_xsendfile`` installed on your apache server you can
 configure the settings.
 
 in ``settings.py``::
-    
+
     FILER_SERVERS = {
         'private': {
             'main': {
@@ -99,8 +131,11 @@ in ``settings.py``::
         }
 
 in your apache configuration::
-    
+
     XSendFilePath /path/to/smedia/
 
 ``XSendFilePath`` is a whitelist for directories where apache will serve files
 from.
+
+
+.. _Django: http://djangoproject.com

docs/settings.rst

@@ -7,17 +7,17 @@ Settings
 ----------------------------
 
 Activate the or not the Permission check on the files and folders before 
-displaying them in the admin. When set to false it give all the authorization
-to staff members.
+displaying them in the admin. When set to ``False`` it gives all the authorization
+to staff members based on standard Django model permissions.
 
-Defaults to ``True``
+Defaults to ``False``
 
 ``FILER_IS_PUBLIC_DEFAULT``
 ---------------------------
 
 Should newly uploaded files have permission checking disabled (be public) by default.
 
-Defaults to ``False`` (new files have permission checking enabled, are private)
+Defaults to ``False`` (new files have permission checking disable, are public)
 
 .. _FILER_STATICMEDIA_PREFIX:
 
@@ -31,6 +31,7 @@ Defaults to ``<STATIC_URL>/filer/`` if ``STATIC_URL`` is defined. Otherwise
 falls back to ``<MEDIA_URL>/filer/``. It is the URL where the ``static/filer/`` 
 directory should be served.
 
+.. _FILER_STORAGES:
 
 ``FILER_STORAGES``
 ------------------
@@ -116,15 +117,15 @@ Defaults to using the DefaultServer (doh)! This will serve the files with the dj
 The number of items (Folders, Files) that should be displayed per page in
 admin.
 
-Defaults to `20`
+Defaults to ``20``
 
 ``FILER_SUBJECT_LOCATION_IMAGE_DEBUG``
 --------------------------------------
 
 Draws a red circle around to point in the image that was used to do the 
 subject location aware image cropping.
 
-Defaults to `False`
+Defaults to ``False``
 
 ``FILER_ALLOW_REGULAR_USERS_TO_ADD_ROOT_FOLDERS``
 -------------------------------------------------