From bf717eff6420af78a41e1359cdd7b9e409076281 Mon Sep 17 00:00:00 2001
From: Paul Oswald
Date: Wed, 15 Feb 2012 10:31:56 +0900
Subject: Documentation on how to override the template; Closes Issue #165
---
docs/howto/setup.rst | 13 +++++++++++++
1 file changed, 13 insertions(+)
(limited to 'docs/howto')
diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst
index 22f98f0c..d018c72d 100644
--- a/docs/howto/setup.rst
+++ b/docs/howto/setup.rst
@@ -29,6 +29,19 @@ but once you move onto a production server, you'll want to make sure you serve t
* 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)
+You may customize the templates by creating a new template called ``djangorestframework/renderer.html``
+in your project, extend ``djangorestframework/base_renderer.html`` and override the
+appropriate ``{% block tags %}``. For example::
+
+ {% extends "djangorestframework/base_renderer.html" %}
+
+ {% block title %}My API{% endblock %}
+
+ {% block branding %}
+ My API
+ {% endblock %}
+
+
Markdown
--------
--
cgit v1.2.3
From 50198935af1f772835a3c26943cbb245295c60e5 Mon Sep 17 00:00:00 2001
From: Paul Oswald
Date: Mon, 20 Feb 2012 22:16:51 +0900
Subject: Rename templates to 'base.html', 'api.html', 'api.txt' and
'login.html'
---
docs/howto/setup.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
(limited to 'docs/howto')
diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst
index d018c72d..64b58262 100644
--- a/docs/howto/setup.rst
+++ b/docs/howto/setup.rst
@@ -29,11 +29,11 @@ but once you move onto a production server, you'll want to make sure you serve t
* 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)
-You may customize the templates by creating a new template called ``djangorestframework/renderer.html``
-in your project, extend ``djangorestframework/base_renderer.html`` and override the
+You may customize the templates by creating a new template called ``djangorestframework/api.html``
+in your project, extend ``djangorestframework/base.html`` and override the
appropriate ``{% block tags %}``. For example::
- {% extends "djangorestframework/base_renderer.html" %}
+ {% extends "djangorestframework/base.html" %}
{% block title %}My API{% endblock %}
--
cgit v1.2.3
From 6c5fb562574d4c42a2ecc3eb9109e56599551a11 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Mon, 20 Feb 2012 20:31:41 +0000
Subject: Update docs
---
docs/howto/setup.rst | 74 ++++++++++++++++++++++++++++------------------------
1 file changed, 40 insertions(+), 34 deletions(-)
(limited to 'docs/howto')
diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst
index 64b58262..0af1449c 100644
--- a/docs/howto/setup.rst
+++ b/docs/howto/setup.rst
@@ -3,35 +3,18 @@
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
-
-Template Loaders
-----------------
-
-Django REST framework uses a few templates for the HTML and plain text documenting renderers.
-
-* Ensure ``TEMPLATE_LOADERS`` setting contains ``'django.template.loaders.app_directories.Loader'``.
-
-This will be the case by default so you shouldn't normally need to do anything here.
-
-Admin 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 `_.
-
-* 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)
-
-You may customize the templates by creating a new template called ``djangorestframework/api.html``
-in your project, extend ``djangorestframework/base.html`` and override the
-appropriate ``{% block tags %}``. For example::
+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::
{% extends "djangorestframework/base.html" %}
@@ -42,19 +25,36 @@ appropriate ``{% block tags %}``. For example::
{% endblock %}
+Styling
+-------
+
+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``
+
+
Markdown
--------
-The Python `markdown library `_ 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
-`_ 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
@@ -64,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
--
cgit v1.2.3
From 86d470796e077e8c3c2253bba26cd7550f5d8f33 Mon Sep 17 00:00:00 2001
From: Daniel Izquierdo
Date: Tue, 21 Feb 2012 15:23:31 +0900
Subject: Add a HOWTO page for the custom `reverse()'
---
docs/howto/reverse.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 47 insertions(+)
create mode 100644 docs/howto/reverse.rst
(limited to 'docs/howto')
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
--
cgit v1.2.3
From ca9465f11e3310b7b1e18cd893e96b69963f68c9 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Tue, 21 Feb 2012 20:47:55 +0000
Subject: reverse gets it's own module
---
docs/howto/reverse.rst | 18 +++++-------------
1 file changed, 5 insertions(+), 13 deletions(-)
(limited to 'docs/howto')
diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst
index e4efbbca..73b8fa4d 100644
--- a/docs/howto/reverse.rst
+++ b/docs/howto/reverse.rst
@@ -1,12 +1,6 @@
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:
@@ -23,9 +17,9 @@ There's no requirement for you to use them, but if you do then the self-describi
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::
+The :py:func:`~reverse.reverse` function has the same behavior as `django.core.urlresolvers.reverse`_, 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.reverse import reverse
from djangorestframework.views import View
class MyView(View):
@@ -39,9 +33,7 @@ The :py:func:`~utils.reverse` function has the same behavior as :py:func:`django
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
+The :py:func:`~reverse.reverse_lazy` function has the same behavior as `django.core.urlresolvers.reverse_lazy`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port.
-.. [1] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse
-.. [2] https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy
+.. _django.core.urlresolvers.reverse: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse
+.. _django.core.urlresolvers.reverse_lazy: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy
--
cgit v1.2.3
From 66eabe8bd1a539f92c3d677565d69edc29a1721b Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Tue, 21 Feb 2012 22:50:41 +0000
Subject: Remove staticviews. Use standard login/logout
---
docs/howto/setup.rst | 17 +++++++++--------
1 file changed, 9 insertions(+), 8 deletions(-)
(limited to 'docs/howto')
diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst
index 0af1449c..f0127060 100644
--- a/docs/howto/setup.rst
+++ b/docs/howto/setup.rst
@@ -53,16 +53,17 @@ YAML support is optional, and requires `PyYAML`_.
Login / Logout
--------------
-Django REST framework includes login and logout views that are useful if
-you're using the self-documenting API::
+Django REST framework includes login and logout views that are needed if
+you're using the self-documenting API.
- from django.conf.urls.defaults import patterns
+Make sure you include the following in your `urlconf`::
- urlpatterns = patterns('djangorestframework.views',
- # Add your resources here
- (r'^accounts/login/$', 'api_login'),
- (r'^accounts/logout/$', 'api_logout'),
- )
+ from django.conf.urls.defaults import patterns, url
+
+ urlpatterns = patterns('',
+ ...
+ url(r'^restframework', include('djangorestframework.urls', namespace='djangorestframework'))
+ )
.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/
.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
--
cgit v1.2.3