diff options
| -rw-r--r-- | README.md | 34 | ||||
| -rw-r--r-- | docs/index.md | 19 | ||||
| -rw-r--r-- | docs/topics/release-notes.md | 39 |
3 files changed, 76 insertions, 16 deletions
@@ -39,14 +39,46 @@ There is also a sandbox API you can use for testing purposes, [available here][s # Installation -Install using `pip`... +Install using `pip`, including any optional packages you want... pip install djangorestframework + pip install markdown # Markdown support for the browseable API. + pip install pyyaml # YAML content-type support. + pip install django-filter # Filtering support ...or clone the project from github. git clone git@github.com:tomchristie/django-rest-framework.git + cd django-rest-framework pip install -r requirements.txt + pip install -r optionals.txt + +Add `'rest_framework'` to your `INSTALLED_APPS` setting. + + INSTALLED_APPS = ( + ... + 'rest_framework', + ) + +## Browseable API requirements + +If you're intending to use the browseable API you'll also want to also ensure you include `'django.contrib.staticfiles'` in your `INSTALLED_APPS` setting. + + INSTALLED_APPS = ( + ... + 'django.contrib.staticfiles', + 'rest_framework', + ) + +You'll proabably also want to add REST framework's login and logout views. +Add the following to your root `urls.py` file. + + urlpatterns = patterns('', + ... + url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) + ) + +Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. # Development diff --git a/docs/index.md b/docs/index.md index cc0f2a13..5d90e9e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ Django REST framework is a lightweight library that makes it easy to build Web A Web APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. -If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcment][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. +If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcement][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. There is also a sandbox API you can use for testing purposes, [available here][sandbox]. @@ -52,21 +52,32 @@ Install using `pip`, including any optional packages you want... pip install -r requirements.txt pip install -r optionals.txt -Add `rest_framework` to your `INSTALLED_APPS`. +Add `'rest_framework'` to your `INSTALLED_APPS` setting. INSTALLED_APPS = ( ... 'rest_framework', ) -If you're intending to use the browseable API you'll want to add REST framework's login and logout views. Add the following to your root `urls.py` file. +### Browseable API requirements + +If you're intending to use the browseable API you'll also want to also ensure you include `'django.contrib.staticfiles'` in your `INSTALLED_APPS` setting. + + INSTALLED_APPS = ( + ... + 'django.contrib.staticfiles', + 'rest_framework', + ) + +You'll proabably also want to add REST framework's login and logout views. +Add the following to your root `urls.py` file. urlpatterns = patterns('', ... url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) ) -Note that the URL path can be whatever you want, but you must include `rest_framework.urls` with the `rest_framework` namespace. +Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. ## Quickstart diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 71fa3c03..1934292c 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -4,12 +4,27 @@ > > — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. -## 2.1.x series +## Versioning + +Minor version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between minor point releases without any other code changes. + +Medium version numbers (0.x.0) may include minor API changes. You should read the release notes carefully before upgrading between medium point releases. -### Master +## 2.2.x series +### 2.2.0 + +**Date**: 27th Dec 2012 + +* Support configurable `STATICFILES_STORAGE` storage. * Bugfix: Related fields now respect the required flag, and may be required=False. +**API-incompatible changes**: From 2.2.0 Onwards you must make sure to include `'django.contrib.staticfiles'` in your `INSTALLED_APPS`. This is in line with Django's 1.4's recommended usage of [the `'staticfiles'` template tag][staticfiles14] instead of Django 1.3's recommended usage of [the `'static'` template tag][staticfiles13]. + +--- + +## 2.1.x series + ### 2.1.12 **Date**: 21st Dec 2012 @@ -105,7 +120,7 @@ * Support use of HTML exception templates. Eg. `403.html` * Hyperlinked fields take optional `slug_field`, `slug_url_kwarg` and `pk_url_kwarg` arguments. -* Bugfix: Deal with optional trailing slashs properly when generating breadcrumbs. +* Bugfix: Deal with optional trailing slashes properly when generating breadcrumbs. * Bugfix: Make textareas same width as other fields in browsable API. * Private API change: `.get_serializer` now uses same `instance` and `data` ordering as serializer initialization. @@ -113,8 +128,6 @@ **Date**: 5th Nov 2012 -**Warning**: Please read [this thread][2.1.0-notes] regarding the `instance` and `data` keyword args before updating to 2.1.0. - * **Serializer `instance` and `data` keyword args have their position swapped.** * `queryset` argument is now optional on writable model fields. * Hyperlinked related fields optionally take `slug_field` and `slug_url_kwarg` arguments. @@ -123,6 +136,8 @@ * Bugfix: Support choice field in Browseable API. * Bugfix: Related fields with `read_only=True` do not require a `queryset` argument. +**API-incompatible changes**: Please read [this thread][2.1.0-notes] regarding the `instance` and `data` keyword args before updating to 2.1.0. + --- ## 2.0.x series @@ -159,9 +174,9 @@ * Allow views to specify template used by TemplateRenderer * More consistent error responses * Some serializer fixes -* Fix internet explorer ajax behaviour +* Fix internet explorer ajax behavior * Minor xml and yaml fixes -* Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) +* Improve setup (e.g. use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) * Sensible absolute URL generation, not using hacky set_script_prefix --- @@ -172,13 +187,13 @@ * Added DjangoModelPermissions class to support `django.contrib.auth` style permissions. * Use `staticfiles` for css files. - - Easier to override. Won't conflict with customised admin styles (eg grappelli) + - Easier to override. Won't conflict with customized admin styles (e.g. grappelli) * Templates are now nicely namespaced. - Allows easier overriding. * Drop implied 'pk' filter if last arg in urlconf is unnamed. - - Too magical. Explict is better than implicit. -* Saner template variable autoescaping. -* Tider setup.py + - Too magical. Explicit is better than implicit. +* Saner template variable auto-escaping. +* Tidier setup.py * Updated for URLObject 2.0 * Bugfixes: - Bug with PerUserThrottling when user contains unicode chars. @@ -266,5 +281,7 @@ * Initial release. [cite]: http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html +[staticfiles14]: https://docs.djangoproject.com/en/1.4/howto/static-files/#with-a-template-tag +[staticfiles13]: https://docs.djangoproject.com/en/1.3/howto/static-files/#with-a-template-tag [2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion [announcement]: rest-framework-2-announcement.md |