Documentation reorganization

docs/contents.rst

@@ -3,8 +3,8 @@ Documentation
 
 .. toctree::
   :maxdepth: 2
-  
-  howto
+
+  guides
   library
   examples
-  
+

docs/examples.rst

@@ -3,21 +3,21 @@ Examples
 
 There are a few real world web API examples included with Django REST framework.
 
+#. :doc:`examples/resourceexample`
+#. :doc:`examples/modelresourceexample`
 #. :doc:`examples/objectstore` - Using :class:`views.View` classes for APIs that do not map to models.
 #. :doc:`examples/pygments` - Using :class:`views.View` classes with forms for input validation.
 #. :doc:`examples/blogpost` - Using :class:`views.ModelView` classes for APIs that map directly to models.
+#. :doc:`examples/permissions` - How to protect your API using authentication and throttling
 
 All the examples are freely available for testing in the sandbox:
 
     http://rest.ep.io
 
-(The :doc:`examples/sandbox` resource is also documented.)
-
-Example Reference
------------------
+There is also documentation describing how the :doc:`examples/sandbox` resource itself is implemented.
 
 .. toctree::
-  :maxdepth: 1
+  :hidden:
   :glob:
 
   examples/*

docs/examples/modelresourceexample.rst

@@ -1,10 +1,10 @@
-Getting Started - Model Views
------------------------------
+Model Resource Example
+----------------------
 
 .. note::
 
     A live sandbox instance of this API is available:
-    
+
     http://rest.ep.io/model-resource-example/
 
     You can browse the API using a web browser, or from the command line::

docs/examples/resourceexample.rst

@@ -1,10 +1,10 @@
-Getting Started - Views
------------------------
+Resource Example
+----------------
 
 .. note::
 
     A live sandbox instance of this API is available:
-    
+
     http://rest.ep.io/resource-example/
 
     You can browse the API using a web browser, or from the command line::

docs/guides.rst

@@ -0,0 +1,8 @@
+Guides
+======
+
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  guides/*

docs/guides/alternativeframeworks.rst

@@ -19,6 +19,7 @@ The big benefits of using Django REST framework come down to:
 1. It's based on Django's class based views, which makes it simple, modular, and future-proof.
 2. It stays as close as possible to Django idioms and language throughout.
 3. The browse-able API makes working with the APIs extremely quick and easy.
+4. Stay true to REST by default while still allowing pragmatic optimizations to be implemented if needed.
 
 
 Why was this project created?

docs/guides/reverse.rst

@@ -1,5 +1,5 @@
-Returning URIs from your Web APIs
-=================================
+Returning URIs as Resource Id's from your Web APIs
+==================================================
 
 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".
 
@@ -21,7 +21,7 @@ The :py:func:`~reverse.reverse` function has the same behavior as `django.core.u
 
     from djangorestframework.reverse import reverse
     from djangorestframework.views import View
-   
+
     class MyView(View):
         def get(self, request):
             context = {

docs/guides/setup.rst

@@ -41,7 +41,7 @@ Markdown
 
 `Python markdown`_ is not required but comes recommended.
 
-If markdown is installed your :class:`.Resource` descriptions can include
+If markdown is installed, your :class:`.Resource` descriptions can include
 `markdown formatting`_ which will be rendered by the self-documenting API.
 
 YAML
@@ -62,11 +62,11 @@ Make sure you include the following in your `urlconf`::
     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/
 .. _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
+.. _PyYAML: http://pypi.python.org/pypi/PyYAML

docs/guides/usingcurl.rst

@@ -1,4 +1,4 @@
-Using CURL with django-rest-framework
+Using curl with Django REST Framework
 =====================================
 
 `curl <http://curl.haxx.se/>`_ is a great command line tool for making requests to URLs.

docs/howto.rst

@@ -1,8 +0,0 @@
-How Tos, FAQs & Notes
-=====================
-
-.. toctree::
-  :maxdepth: 1
-  :glob:
-
-  howto/*

docs/index.rst

@@ -9,32 +9,21 @@ Django REST framework
 Introduction
 ------------
 
-Django REST framework is a lightweight REST framework for Django, that aims to make it easy to build well-connected, self-describing RESTful Web APIs.
+Django REST framework is a lightweight framework for Django, that makes it easy to build well-connected, self-describing RESTful Web APIs.
 
-**Browse example APIs created with Django REST framework:** `The Sandbox <http://rest.ep.io/>`_
+**Check out some example APIs created with Django REST framework in** `The Sandbox <http://rest.ep.io/>`_
 
 Features:
 ---------
 
-* Automatically provides an awesome Django admin style `browse-able self-documenting API <http://rest.ep.io>`_.
-* Clean, simple, views for Resources, using Django's new `class based views <http://docs.djangoproject.com/en/dev/topics/class-based-views/>`_.
+* Automatically provides an awesome Django admin style `browsable self-documenting API <http://rest.ep.io>`_.
+* Clean, simple views for Resources using Django's new `class based views <http://docs.djangoproject.com/en/dev/topics/class-based-views/>`_.
 * Support for ModelResources with out-of-the-box default implementations and input validation.
 * Pluggable :mod:`.parsers`, :mod:`renderers`, :mod:`authentication` and :mod:`permissions` - Easy to customise.
 * Content type negotiation using HTTP Accept headers.
 * Optional support for forms as input validation.
 * Modular architecture - MixIn classes can be used without requiring the :class:`.Resource` or :class:`.ModelResource` classes.
 
-Resources
----------
-
-**Project hosting:** `GitHub <https://github.com/tomchristie/django-rest-framework>`_.
-
-* The ``djangorestframework`` package is `available on PyPI <http://pypi.python.org/pypi/djangorestframework>`_.
-* We have an active `discussion group <http://groups.google.com/group/django-rest-framework>`_.
-* Bug reports are handled on the `issue tracker <https://github.com/tomchristie/django-rest-framework/issues>`_.
-* There is a `Jenkins CI server <http://jenkins.tibold.nl/job/djangorestframework/>`_ which tracks test status and coverage reporting.  (Thanks Marko!)
-
-Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*.
 
 Requirements
 ------------
@@ -46,32 +35,6 @@ Requirements
 * `Markdown`_ >= 2.1.0 (Optional)
 * `PyYAML`_ >= 3.10 (Optional)
 
-Installation
-------------
-
-You can install Django REST framework using ``pip`` or ``easy_install``::
-
-    pip install djangorestframework
-
-Or get the latest development version using git::
-
-    git clone git@github.com:tomchristie/django-rest-framework.git
-
-Setup
------
-
-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.
 
 Getting Started
 ---------------
@@ -80,7 +43,7 @@ Using Django REST framework can be as simple as adding a few lines to your urlco
 
 The following example exposes your `MyModel` model through an api. It will provide two views:
 
- * A view which lists your model instances and simultaniously allows creation of instances 
+ * A view which lists your model instances and simultaniously allows creation of instances
    from that view.
 
  * Another view which lets you view, update or delete  your model instances individually.
@@ -100,15 +63,57 @@ The following example exposes your `MyModel` model through an api. It will provi
         url(r'^(?P<pk>[^/]+)/$', InstanceModelView.as_view(resource=MyResource)),
     )
 
-.. include:: howto.rst
+
+Installation
+------------
+
+You can install Django REST framework using ``pip`` or ``easy_install``::
+
+    pip install djangorestframework
+
+Or get the latest development version using git::
+
+    git clone git@github.com:tomchristie/django-rest-framework.git
+
+
+Setup
+-----
+
+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 customizing your installation, take a look at the :ref:`setup` section.
+
+
+Resources
+---------
+
+Project hosting: `GitHub <https://github.com/tomchristie/django-rest-framework>`_.
+
+* The ``djangorestframework`` package is `available on PyPI <http://pypi.python.org/pypi/djangorestframework>`_.
+* We have an active `discussion group <http://groups.google.com/group/django-rest-framework>`_.
+* Bug reports are handled on the `issue tracker <https://github.com/tomchristie/django-rest-framework/issues>`_.
+* There is a `Jenkins CI server <http://jenkins.tibold.nl/>`_ which tracks test status and coverage reporting.  (Thanks Marko!)
+
+Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*.
+
+
+.. include:: guides.rst
 
 .. include:: library.rst
 
-
 .. include:: examples.rst
 
 .. toctree::
-  :hidden: 
+  :hidden:
 
   contents
 

docs/library/compat.rst

@@ -1,5 +1,5 @@
-:mod:`compat`
-=====================
-
-.. automodule:: compat
-   :members:
+:mod:`compat`
+=====================
+
+.. automodule:: compat
+   :members:

docs/library/mixins.rst

@@ -1,5 +1,5 @@
-:mod:`mixins`
-=====================
-
-.. automodule:: mixins
-   :members:
+:mod:`mixins`
+=====================
+
+.. automodule:: mixins
+   :members:

docs/library/permissions.rst

@@ -1,5 +1,5 @@
-:mod:`permissions`
-=====================
-
-.. automodule:: permissions
-   :members:
+:mod:`permissions`
+=====================
+
+.. automodule:: permissions
+   :members:

docs/library/views.rst

@@ -1,5 +1,5 @@
-:mod:`views`
-=====================
-
-.. automodule:: views
-   :members:
+:mod:`views`
+=====================
+
+.. automodule:: views
+   :members: