diff --git a/docs/contents.rst b/docs/contents.rst index d8e6e7428..ab490ddfa 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -3,8 +3,8 @@ Documentation .. toctree:: :maxdepth: 2 - - howto + + guides library examples - + diff --git a/docs/examples.rst b/docs/examples.rst index 640883454..e4a2768e2 100644 --- a/docs/examples.rst +++ b/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/* diff --git a/docs/examples/modelviews.rst b/docs/examples/modelresourceexample.rst similarity index 96% rename from docs/examples/modelviews.rst rename to docs/examples/modelresourceexample.rst index b67d50d9e..43d4345f5 100644 --- a/docs/examples/modelviews.rst +++ b/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:: diff --git a/docs/examples/views.rst b/docs/examples/resourceexample.rst similarity index 97% rename from docs/examples/views.rst rename to docs/examples/resourceexample.rst index db0db0d70..91ddd4e55 100644 --- a/docs/examples/views.rst +++ b/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:: diff --git a/docs/guides.rst b/docs/guides.rst new file mode 100644 index 000000000..f53570925 --- /dev/null +++ b/docs/guides.rst @@ -0,0 +1,8 @@ +Guides +====== + +.. toctree:: + :maxdepth: 1 + :glob: + + guides/* diff --git a/docs/howto/alternativeframeworks.rst b/docs/guides/alternativeframeworks.rst similarity index 94% rename from docs/howto/alternativeframeworks.rst rename to docs/guides/alternativeframeworks.rst index dc8d1ea65..d18ea1b50 100644 --- a/docs/howto/alternativeframeworks.rst +++ b/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? diff --git a/docs/howto/mixin.rst b/docs/guides/mixin.rst similarity index 100% rename from docs/howto/mixin.rst rename to docs/guides/mixin.rst diff --git a/docs/howto/reverse.rst b/docs/guides/reverse.rst similarity index 94% rename from docs/howto/reverse.rst rename to docs/guides/reverse.rst index 73b8fa4df..4a30a4ba2 100644 --- a/docs/howto/reverse.rst +++ b/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 = { diff --git a/docs/howto/setup.rst b/docs/guides/setup.rst similarity index 94% rename from docs/howto/setup.rst rename to docs/guides/setup.rst index 081c64128..bc1454e44 100644 --- a/docs/howto/setup.rst +++ b/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 \ No newline at end of file +.. _PyYAML: http://pypi.python.org/pypi/PyYAML diff --git a/docs/howto/usingcurl.rst b/docs/guides/usingcurl.rst similarity index 96% rename from docs/howto/usingcurl.rst rename to docs/guides/usingcurl.rst index eeb8da062..9764f0a34 100644 --- a/docs/howto/usingcurl.rst +++ b/docs/guides/usingcurl.rst @@ -1,4 +1,4 @@ -Using CURL with django-rest-framework +Using curl with Django REST Framework ===================================== `curl `_ is a great command line tool for making requests to URLs. diff --git a/docs/howto/usingurllib2.rst b/docs/guides/usingurllib2.rst similarity index 100% rename from docs/howto/usingurllib2.rst rename to docs/guides/usingurllib2.rst diff --git a/docs/howto.rst b/docs/howto.rst deleted file mode 100644 index 8fdc09267..000000000 --- a/docs/howto.rst +++ /dev/null @@ -1,8 +0,0 @@ -How Tos, FAQs & Notes -===================== - -.. toctree:: - :maxdepth: 1 - :glob: - - howto/* diff --git a/docs/index.rst b/docs/index.rst index a6745fca5..bbb1779f6 100644 --- a/docs/index.rst +++ b/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 `_ +**Check out some example APIs created with Django REST framework in** `The Sandbox `_ Features: --------- -* Automatically provides an awesome Django admin style `browse-able self-documenting API `_. -* Clean, simple, views for Resources, using Django's new `class based views `_. +* Automatically provides an awesome Django admin style `browsable self-documenting API `_. +* Clean, simple views for Resources using Django's new `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 `_. - -* The ``djangorestframework`` package is `available on PyPI `_. -* We have an active `discussion group `_. -* Bug reports are handled on the `issue tracker `_. -* There is a `Jenkins CI server `_ 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[^/]+)/$', 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 `_. + +* The ``djangorestframework`` package is `available on PyPI `_. +* We have an active `discussion group `_. +* Bug reports are handled on the `issue tracker `_. +* There is a `Jenkins CI server `_ 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 diff --git a/docs/library/compat.rst b/docs/library/compat.rst index 93fb081a0..7f6658ae4 100644 --- a/docs/library/compat.rst +++ b/docs/library/compat.rst @@ -1,5 +1,5 @@ -:mod:`compat` -===================== - -.. automodule:: compat - :members: +:mod:`compat` +===================== + +.. automodule:: compat + :members: diff --git a/docs/library/mixins.rst b/docs/library/mixins.rst index 04bf66b06..665f675dc 100644 --- a/docs/library/mixins.rst +++ b/docs/library/mixins.rst @@ -1,5 +1,5 @@ -:mod:`mixins` -===================== - -.. automodule:: mixins - :members: +:mod:`mixins` +===================== + +.. automodule:: mixins + :members: diff --git a/docs/library/permissions.rst b/docs/library/permissions.rst index c694d639a..2a710c79a 100644 --- a/docs/library/permissions.rst +++ b/docs/library/permissions.rst @@ -1,5 +1,5 @@ -:mod:`permissions` -===================== - -.. automodule:: permissions - :members: +:mod:`permissions` +===================== + +.. automodule:: permissions + :members: diff --git a/docs/library/views.rst b/docs/library/views.rst index 329b487b7..ff0e0dfae 100644 --- a/docs/library/views.rst +++ b/docs/library/views.rst @@ -1,5 +1,5 @@ -:mod:`views` -===================== - -.. automodule:: views - :members: +:mod:`views` +===================== + +.. automodule:: views + :members: