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') 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') 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 ++++++++++++++++++++++++++++------------------------ docs/index.rst | 14 +++++++--- 2 files changed, 50 insertions(+), 38 deletions(-) (limited to 'docs') 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 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 `_. - 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 -- 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') 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 8f5b093c0d0db7b50bd197abfc8dc137f794b8e7 Mon Sep 17 00:00:00 2001 From: Daniel Izquierdo Date: Tue, 21 Feb 2012 15:29:47 +0900 Subject: Include the `utils' module in the docs --- docs/library/utils.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/library/utils.rst (limited to 'docs') 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: -- 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 +++++------------- docs/library/reverse.rst | 5 +++++ docs/library/utils.rst | 5 ----- 3 files changed, 10 insertions(+), 18 deletions(-) create mode 100644 docs/library/reverse.rst delete mode 100644 docs/library/utils.rst (limited to 'docs') 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 diff --git a/docs/library/reverse.rst b/docs/library/reverse.rst new file mode 100644 index 00000000..a2c29c48 --- /dev/null +++ b/docs/library/reverse.rst @@ -0,0 +1,5 @@ +:mod:`reverse` +================ + +.. automodule:: reverse + :members: diff --git a/docs/library/utils.rst b/docs/library/utils.rst deleted file mode 100644 index 653f24fd..00000000 --- a/docs/library/utils.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`utils` -============== - -.. automodule:: utils - :members: -- 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 +++++++++-------- docs/index.rst | 6 ++++++ 2 files changed, 15 insertions(+), 8 deletions(-) (limited to 'docs') 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/ diff --git a/docs/index.rst b/docs/index.rst index b969c4a3..a6745fca 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -64,6 +64,12 @@ To add Django REST framework to a Django project: * Ensure that the ``djangorestframework`` directory is on your ``PYTHONPATH``. * Add ``djangorestframework`` to your ``INSTALLED_APPS``. +* Add the following to your URLconf. (To include the REST framework Login/Logout views.):: + + urlpatterns = patterns('', + ... + url(r'^restframework', include('djangorestframework.urls', namespace='djangorestframework')) + ) For more information on settings take a look at the :ref:`setup` section. -- cgit v1.2.3 From 1751655927735ecd8a096889014f4e0beeba101a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 27 Feb 2012 10:06:20 +0000 Subject: Update docs/requirements.txt --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/requirements.txt b/docs/requirements.txt index 77cdf485..46a67149 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,6 @@ # Documentation requires Django & Sphinx, and their dependencies... -Django==1.2.4 +Django>=1.2.4 Jinja2==2.5.5 Pygments==1.4 Sphinx==1.0.7 -- cgit v1.2.3