From 0bf5fbfa76544fe921d051619127748ae10237bd Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Mon, 31 Jan 2011 22:06:53 +0000 Subject: [PATCH] Some tweaks to the staticfiles docs to clarify things for new users. Thanks Jannis and brutasse for review and discussion. * Rearranged 'in a nutshell' usage docs to clarify app-dirs vs STATICFILES_DIRS, initially focus on the simplest path to working local dev, and remove the need for repetitive 'you don't need this in local dev' notes. * Added docs on using staticfiles serve view for non-staticfiles (e.g. user-uploaded files). git-svn-id: http://code.djangoproject.com/svn/django/trunk@15380 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/static-files.txt | 116 ++++++++++++++----------------- docs/ref/contrib/staticfiles.txt | 32 ++++++++- 2 files changed, 84 insertions(+), 64 deletions(-) diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index e5b97403a18..94e04bb738e 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -7,7 +7,7 @@ Managing static files .. versionadded:: 1.3 Django developers mostly concern themselves with the dynamic parts of web -applications -- the views and templates that render new for each request. But +applications -- the views and templates that render anew for each request. But web applications have other parts: the static files (images, CSS, Javascript, etc.) that are needed to render a complete web page. @@ -38,69 +38,30 @@ Using ``django.contrib.staticfiles`` Here's the basic usage in a nutshell: - 1. Put your static files somewhere that staticfiles will find it. + 1. Put your static files somewhere that ``staticfiles`` will find them. - Most of the time this place will be in a ``static`` directory within - your application, but it could also be a specific directory you've put - into your settings file. See the the documentation for the - :setting:`STATICFILES_DIRS` and :setting:`STATICFILES_FINDERS` settings - for details on where you can put static files. + By default, this means within ``static/`` subdirectories of apps in your + :setting:`INSTALLED_APPS`. - 2. Add some ``staticfiles``-related settings to your settings file. + Many projects will also have static assets that aren't tied to a + particular app; you can give ``staticfiles`` additional directories to + search via the :setting:`STATICFILES_DIRS` setting . - First, you'll need to make sure that ``django.contrib.staticfiles`` - is in your :setting:`INSTALLED_APPS`. + See the documentation for the :setting:`STATICFILES_FINDERS` setting for + details on how ``staticfiles`` finds your files. - Next, you'll need to set the :setting:`STATIC_URL` setting, though - the default value (of ``'/static/'``) is perfect for local development. - See also the :setting:`STATIC_URL` documentation. + 2. Make sure that ``django.contrib.staticfiles`` is in your + :setting:`INSTALLED_APPS`. - Then, edit the :setting:`STATIC_ROOT` setting to point to where - you'd like your static files collected at (when using the - :djadmin:`collectstatic`, see below). For example:: + For :ref:`local development`, if you are using + :ref:`runserver` or adding + :ref:`staticfiles_urlpatterns` to your URLconf, + you're done! Your static files will automatically be served at the + default :setting:`STATIC_URL` of ``/static/``. - STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic" - - There are a number of other options available that let you control - *how* static files are stored, where ``staticfiles`` searches for - files, and how files will be served; see :ref:`the staticfiles - settings reference ` for details. - - 3. Run the :djadmin:`collectstatic` management command:: - - ./manage.py collectstatic - - This'll churn through your static file storage and move them into the - directory given by :setting:`STATIC_ROOT`. - - .. note:: This is **not necessary in local development** if you are - using :djadmin:`runserver` or adding - ``staticfiles_urlpatterns`` to your URLconf; see below). - - 4. Deploy those files. - - If you're using the built-in development server (the - :djadmin:`runserver` management command) and have the :setting:`DEBUG` - setting set to ``True``, your staticfiles will automatically be served - from :setting:`STATIC_URL` in development. You don't need to run - :djadmin:`collectstatic` in that case because ``staticfiles``'s - runserver command handle the serving of static files. - - But, in case you are using some other server for local development, - you can quickly serve static files locally by adding:: - - from django.contrib.staticfiles.urls import staticfiles_urlpatterns - urlpatterns += staticfiles_urlpatterns() - - to the bottom of your URLconf. See :ref:`staticfiles-development` for - details. - - When it comes time to deploy to production, :ref:`staticfiles-production` - covers some common deployment strategies for static files. - - However you choose to deploy those files, you'll probably need to refer - to them in your templates. The easiest method is to use the included - context processor which will allow template code like: + 3. You'll probably need to refer to these files in your templates. The + easiest method is to use the included context processor which will allow + template code like: .. code-block:: html+django @@ -109,6 +70,31 @@ Here's the basic usage in a nutshell: See :ref:`staticfiles-in-templates` for more details, including an alternate method (using a template tag). +When you're ready to move out of local development and deploy your project: + + 1. Set the :setting:`STATIC_URL` setting to the public URL for your static + files (in some cases, the default value of ``/static/`` may still be + fine). + + 2. Set the :setting:`STATIC_ROOT` setting to point to where you'd like your + static files collected to when you use the :djadmin:`collectstatic` + management command. For example:: + + STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic" + + 3. Run the :djadmin:`collectstatic` management command:: + + ./manage.py collectstatic + + This'll churn through your static file storage and copy them into the + directory given by :setting:`STATIC_ROOT`. + + 4. Deploy those files by configuring your webserver of choice to serve the + files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`. + + :ref:`staticfiles-production` covers some common deployment strategies + for static files. + Those are the basics. For more details on common configuration options, read on; for a detailed reference of the settings, commands, and other bits included with the framework see :doc:`the staticfiles reference `. @@ -123,7 +109,10 @@ the framework see :doc:`the staticfiles reference `. :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and :setting:`STATIC_URL`. You will need to arrange for serving of files in :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with - user-uploaded files at all. + user-uploaded files at all. You can, however, use ``staticfiles``' + :func:`~django.contrib.staticfiles.views.serve` view for serving + :setting:`MEDIA_ROOT` in development; see + :ref:`staticfiles-serve-other-directories`. .. _staticfiles-in-templates: @@ -221,7 +210,8 @@ developing locally. Thus, the ``staticfiles`` app ships with a development. This view is automatically enabled and will serve your static files at -:setting:`STATIC_URL` when you use the built-in :djadmin:`runserver`. +:setting:`STATIC_URL` when you use the built-in +:ref:`runserver` management command. To enable this view if you are using some other server for local development, you'll add a couple of lines to your URLconf. The first line goes at the top @@ -275,7 +265,7 @@ If you want to serve your static files from the same server that's already serving your site, the basic outline gets modified to look something like: * Push your code up to the deployment server. - * On the server, run :djadmin:`collectstatic` to move all the static files + * On the server, run :djadmin:`collectstatic` to copy all the static files into :setting:`STATIC_ROOT`. * Point your web server at :setting:`STATIC_ROOT`. For example, here's :ref:`how to do this under Apache and mod_wsgi `. @@ -426,8 +416,8 @@ you're upgrading from `django-staticfiles`_ < ``1.0``` (e.g. ``0.3.4``) to ``staticfiles.storage.StaticFileStorage`` to ``staticfiles.storage.StaticFilesStorage`` - * If using :djadmin:`runserver` for local development (and the - :setting:`DEBUG` setting is ``True``), you no longer need to add + * If using :ref:`runserver` for local development + (and the :setting:`DEBUG` setting is ``True``), you no longer need to add anything to your URLconf for serving static files in development. Learn more diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 2b8fee1200e..4944c284d2c 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -189,10 +189,12 @@ for each relative path, use the ``--first`` option:: This is a debugging aid; it'll show you exactly which static file will be collected for a given path. +.. _staticfiles-runserver: + runserver --------- -.. django-admin:: staticfiles-runserver +.. django-admin:: runserver Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app is :setting:`installed` and adds automatic serving of static @@ -317,3 +319,31 @@ already defined pattern list. Use it like this:: This helper function will only work if :setting:`DEBUG` is ``True`` and your :setting:`STATIC_URL` setting is neither empty nor a full URL such as ``http://static.example.com/``. + +.. _staticfiles-serve-other-directories: + +Serving other directories +""""""""""""""""""""""""" + +There may be files other than your project's static assets that, for +convenience, you'd like to have Django serve for you in local development. The +:func:`~django.contrib.staticfiles.views.serve` view can be used to serve any +directory you give it. (Again, this view is **not** hardened for production +use, and should be used only as a development aid; you should serve these files +in production using a real front-end webserver). + +The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`. +``staticfiles`` is intended for static assets and has no built-in handling for +user-uploaded files, but you can have Django serve your :setting:`MEDIA_ROOT` +by appending something like this to your URLconf:: + + from django.conf import settings + + if settings.DEBUG: + urlpatterns += patterns('django.contrib.staticfiles.views', + url(r'^media/(?P.*)$', 'serve', + {'document_root': settings.MEDIA_ROOT}), + ) + +This snippet assumes you've also set your :setting:`MEDIA_URL` (in development) +to ``/media/``.