From 41ab18b13ec6d96906463a3b05680226c7245b6d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 30 Oct 2012 12:23:17 +0000 Subject: [PATCH] Docs update --- README.md | 26 +++++++++++++------ docs/index.md | 19 +++++++++++--- docs/topics/rest-framework-2-announcement.md | 8 +++++- docs/tutorial/1-serialization.md | 8 ++++++ .../5-relationships-and-hyperlinked-apis.md | 2 +- 5 files changed, 50 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index d74340efb..a6f0438d2 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,23 @@ [![build-status-image]][travis] +--- + +**Full documentation for REST framework is available on [http://django-rest-framework.org][docs].** + +Note that this is the 2.0 version of REST framework. If you are looking for earlier versions please see the [0.4.x branch][0.4] on GitHub. + +--- + # Overview -This branch is the redesign of Django REST framework. It is a work in progress. +Django REST framework is a lightweight library that makes it easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. -For more information, check out [the documentation][docs], in particular, the tutorial is recommended as the best place to get an overview of the redesign. +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. + +There is also a sandbox API you can use for testing purposes, [available here][sandbox]. # Requirements @@ -24,8 +36,6 @@ For more information, check out [the documentation][docs], in particular, the tu # Installation -**Leaving these instructions in for the moment, they'll be valid once this becomes the master version** - Install using `pip`... pip install djangorestframework @@ -35,10 +45,6 @@ Install using `pip`... git clone git@github.com:tomchristie/django-rest-framework.git pip install -r requirements.txt -# Quickstart - -**TODO** - # Development To build the docs. @@ -84,6 +90,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [build-status-image]: https://secure.travis-ci.org/tomchristie/django-rest-framework.png?branch=restframework2 [travis]: http://travis-ci.org/tomchristie/django-rest-framework?branch=restframework2 [twitter]: https://twitter.com/_tomchristie +[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X +[sandbox]: http://restframework.herokuapp.com/ +[rest-framework-2-announcement]: topics/rest-framework-2-announcement.md + [docs]: http://tomchristie.github.com/django-rest-framework/ [urlobject]: https://github.com/zacharyvoase/urlobject [markdown]: http://pypi.python.org/pypi/Markdown/ diff --git a/docs/index.md b/docs/index.md index 4126fc77e..5b6fcd9cb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,12 +5,24 @@ **A toolkit for building well-connected, self-describing Web APIs.** -**WARNING: This documentation is for the 2.0 redesign of REST framework. It is a work in progress.** +--- + +**Note**: This documentation is for the 2.0 version of REST framework. If you are looking for earlier versions please see the [0.4.x branch][0.4] on GitHub. + +--- Django REST framework is a lightweight library that makes it easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. 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. + +There is also a sandbox API you can use for testing purposes, [available here][sandbox]. + +**Below**: *Screenshot from the browseable API* + +![Screenshot][image] + ## Requirements REST framework requires the following: @@ -25,8 +37,6 @@ The following packages are optional: ## Installation -**WARNING: These instructions will only become valid once this becomes the master version** - Install using `pip`, including any optional packages you want... pip install djangorestframework @@ -152,6 +162,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [urlobject]: https://github.com/zacharyvoase/urlobject [markdown]: http://pypi.python.org/pypi/Markdown/ [yaml]: http://pypi.python.org/pypi/PyYAML +[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X +[image]: img/quickstart.png +[sandbox]: http://restframework.herokuapp.com/ [quickstart]: tutorial/quickstart.md [tut-1]: tutorial/1-serialization.md diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index 7b97af73d..e77575b20 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -6,7 +6,13 @@ What it is, and why you should care > > — [Roy Fielding][cite] -REST framework 2 is an almost complete reworking of the original framework, which comprehensivly addresses some of the original design issues. +--- + +**Announcement:** REST framework 2 released - Tue 30th Oct 2012 + +--- + +REST framework 2 is an almost complete reworking of the original framework, which comprehensively addresses some of the original design issues. Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0. diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 7330fdef2..19fc28a5b 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -6,6 +6,12 @@ This tutorial will cover creating a simple pastebin code highlighting Web API. A The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. If you just want a quick overview, you should head over to the [quickstart] documentation instead. +--- + +**Note**: The final code for this tutorial is available in the [tomchristie/rest-framework-tutorial][repo] repository on GitHub. There is also a sandbox version for testing, [available here][sandbox]. + +--- + ## Setting up a new environment Before we do anything else we'll create a new virtual environment, using [virtualenv]. This will make sure our package configuration is keep nicely isolated from any other projects we're working on. @@ -303,5 +309,7 @@ Our API views don't do anything particularly special at the moment, beyond serve We'll see how we can start to improve things in [part 2 of the tutorial][tut-2]. [quickstart]: quickstart.md +[repo]: https://github.com/tomchristie/rest-framework-tutorial +[sandbox]: http://restframework.herokuapp.com/ [virtualenv]: http://www.virtualenv.org/en/latest/index.html [tut-2]: 2-requests-and-responses.md diff --git a/docs/tutorial/5-relationships-and-hyperlinked-apis.md b/docs/tutorial/5-relationships-and-hyperlinked-apis.md index 777aa5e1f..1f663745d 100644 --- a/docs/tutorial/5-relationships-and-hyperlinked-apis.md +++ b/docs/tutorial/5-relationships-and-hyperlinked-apis.md @@ -167,7 +167,7 @@ We've reached the end of our tutorial. If you want to get more involved in the **Now go build some awesome things.** [repo]: https://github.com/tomchristie/rest-framework-tutorial -[sandbox]: http://sultry-coast-6726.herokuapp.com/ +[sandbox]: http://restframework.herokuapp.com/ [github]: https://github.com/tomchristie/django-rest-framework [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [twitter]: https://twitter.com/_tomchristie \ No newline at end of file