Merging master into develop

4 files changed, 104 insertions, 27 deletions

diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst
new file mode 100644
index 00000000..e4efbbca
--- /dev/null
+++ b/docs/howto/reverse.rst
@@ -0,0 +1,47 @@
+Returning URIs from your Web APIs
+=================================
+
+    "The central feature that distinguishes the REST architectural style from
+    other network-based styles is its emphasis on a uniform interface between
+    components."
+
+    -- Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures
+
+As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar".
+
+The advantages of doing so are:
+
+* It's more explicit.
+* It leaves less work for your API clients.
+* There's no ambiguity about the meaning of the string when it's found in representations such as JSON that do not have a native URI type.
+* It allows us to easily do things like markup HTML representations with hyperlinks.
+
+Django REST framework provides two utility functions to make it simpler to return absolute URIs from your Web API.
+
+There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier.
+
+reverse(viewname, request, ...)
+-------------------------------
+
+The :py:func:`~utils.reverse` function has the same behavior as :py:func:`django.core.urlresolvers.reverse` [1]_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port::
+
+    from djangorestframework.utils import reverse
+    from djangorestframework.views import View
+   
+    class MyView(View):
+        def get(self, request):
+            context = {
+                'url': reverse('year-summary', request, args=[1945])
+            }
+
+            return Response(context)
+
+reverse_lazy(viewname, request, ...)
+------------------------------------
+
+The :py:func:`~utils.reverse_lazy` function has the same behavior as :py:func:`django.core.urlresolvers.reverse_lazy` [2]_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port.
+
+.. rubric:: Footnotes
+
+.. [1] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse
+.. [2] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy
diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst
index 22f98f0c..0af1449c 100644
--- a/docs/howto/setup.rst
+++ b/docs/howto/setup.rst
@@ -3,45 +3,58 @@
 Setup
 =====
 
-Installing into site-packages
------------------------------
+Templates
+---------
 
-If you need to manually install Django REST framework to your ``site-packages`` directory, run the ``setup.py`` script::
+Django REST framework uses a few templates for the HTML and plain text
+documenting renderers.  You'll need to ensure ``TEMPLATE_LOADERS`` setting
+contains ``'django.template.loaders.app_directories.Loader'``.
+This will already be the case by default.
 
-    python setup.py install
+You may customize the templates by creating a new template called
+``djangorestframework/api.html`` in your project, which should extend
+``djangorestframework/base.html`` and override the appropriate
+block tags. For example::
 
-Template Loaders
-----------------
+    {% extends "djangorestframework/base.html" %}
 
-Django REST framework uses a few templates for the HTML and plain text documenting renderers.
+    {% block title %}My API{% endblock %}
 
-* Ensure ``TEMPLATE_LOADERS`` setting contains ``'django.template.loaders.app_directories.Loader'``.
+    {% block branding %}
+    <h1 id="site-name">My API</h1>
+    {% endblock %}
 
-This will be the case by default so you shouldn't normally need to do anything here.
 
-Admin Styling
--------------
+Styling
+-------
 
-Django REST framework uses the admin media for styling.  When running using Django's testserver this is automatically served for you, 
-but once you move onto a production server, you'll want to make sure you serve the admin media separately, exactly as you would do 
-`if using the Django admin <https://docs.djangoproject.com/en/dev/howto/deployment/modpython/#serving-the-admin-files>`_.
+Django REST framework requires `django.contrib.staticfiles`_ to serve it's css.
+If you're using Django 1.2 you'll need to use the seperate
+`django-staticfiles`_ package instead.
+
+You can override the styling by creating a file in your top-level static
+directory named ``djangorestframework/css/style.css``
 
-* Ensure that the ``ADMIN_MEDIA_PREFIX`` is set appropriately and that you are serving the admin media. 
-  (Django's testserver will automatically serve the admin media for you)
 
 Markdown
 --------
 
-The Python `markdown library <http://www.freewisdom.org/projects/python-markdown/>`_ is not required but comes recommended.
+`Python markdown`_ is not required but comes recommended.
+
+If markdown is installed your :class:`.Resource` descriptions can include
+`markdown formatting`_ which will be rendered by the self-documenting API.
+
+YAML
+----
+
+YAML support is optional, and requires `PyYAML`_.
 
-If markdown is installed your :class:`.Resource` descriptions can include `markdown style formatting 
-<http://daringfireball.net/projects/markdown/syntax>`_ which will be rendered by the HTML documenting renderer.
 
-login/logout
----------------------------------
+Login / Logout
+--------------
 
-Django REST framework comes with a few views that can be useful including an api
-login and logout views::
+Django REST framework includes login and logout views that are useful if
+you're using the self-documenting API::
 
     from django.conf.urls.defaults import patterns
 
@@ -51,3 +64,9 @@ login and logout views::
         (r'^accounts/logout/$', 'api_logout'),
     )
 
+.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/
+.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
+.. _URLObject: http://pypi.python.org/pypi/URLObject/
+.. _Python markdown: http://www.freewisdom.org/projects/python-markdown/
+.. _markdown formatting: http://daringfireball.net/projects/markdown/syntax
+.. _PyYAML: http://pypi.python.org/pypi/PyYAML
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index ecc1f118..b969c4a3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -40,8 +40,11 @@ Requirements
 ------------
 
 * Python (2.5, 2.6, 2.7 supported)
-* Django (1.2, 1.3, 1.4-alpha supported)
-
+* Django (1.2, 1.3, 1.4 supported)
+* `django.contrib.staticfiles`_ (or `django-staticfiles`_ for Django 1.2)
+* `URLObject`_ >= 2.0.0
+* `Markdown`_ >= 2.1.0 (Optional)
+* `PyYAML`_ >= 3.10 (Optional)
 
 Installation
 ------------
@@ -54,8 +57,6 @@ Or get the latest development version using git::
 
     git clone git@github.com:tomchristie/django-rest-framework.git
 
-Or you can `download the current release <http://pypi.python.org/pypi/djangorestframework>`_.
-
 Setup
 -----
 
@@ -114,3 +115,8 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/
+.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
+.. _URLObject: http://pypi.python.org/pypi/URLObject/
+.. _Markdown: http://pypi.python.org/pypi/Markdown/
+.. _PyYAML: http://pypi.python.org/pypi/PyYAML
diff --git a/docs/library/utils.rst b/docs/library/utils.rst
new file mode 100644
index 00000000..653f24fd
--- /dev/null
+++ b/docs/library/utils.rst
@@ -0,0 +1,5 @@
+:mod:`utils`
+==============
+
+.. automodule:: utils
+   :members: