From 304786657a8cbff323f21b7297c142f6ca5a1cc1 Mon Sep 17 00:00:00 2001 From: markotibold Date: Mon, 16 May 2011 23:54:35 +0200 Subject: [PATCH 1/3] Getting rid of all errors and warnings that show up when building the docs, to make a clean start with the library documentation . --HG-- rename : docs/library/authenticators.rst => docs/library/authentication.rst rename : docs/library/emitters.rst => docs/library/renderers.rst --- docs/examples/blogpost.rst | 6 +++--- docs/index.rst | 8 ++++---- docs/library/authentication.rst | 5 +++++ docs/library/authenticators.rst | 5 ----- docs/library/emitters.rst | 7 ------- docs/library/modelresource.rst | 9 --------- docs/library/renderers.rst | 10 ++++++++++ 7 files changed, 22 insertions(+), 28 deletions(-) create mode 100644 docs/library/authentication.rst delete mode 100644 docs/library/authenticators.rst delete mode 100644 docs/library/emitters.rst delete mode 100644 docs/library/modelresource.rst create mode 100644 docs/library/renderers.rst diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst index 07f7cbc56..9d762f528 100644 --- a/docs/examples/blogpost.rst +++ b/docs/examples/blogpost.rst @@ -27,7 +27,7 @@ Creating the resources Once we have some existing models there's very little we need to do to create the corresponding resources. We simply create a base resource and an instance resource for each model we're working with. django-rest-framework will provide the default operations on the resources all the usual input validation that Django's models can give us for free. -``views.py`` +#``views.py`` -.. include:: ../../examples/blogpost/views.py - :literal: \ No newline at end of file +#.. include:: ../../examples/blogpost/views.py +# :literal: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 4da2da1cb..fac1c94bc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,7 +36,8 @@ Resources Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*. -We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking! (See: `Bitbucket `_, `GitHub `_) +We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking! (See: `Forking a Bitbucket Repository +`_, or `Fork A GitHub Repo `_) Requirements ------------ @@ -140,10 +141,9 @@ Library Reference :maxdepth: 1 library/resource - library/modelresource - library/emitters + library/renderers library/parsers - library/authenticators + library/authentication library/validators library/response library/status diff --git a/docs/library/authentication.rst b/docs/library/authentication.rst new file mode 100644 index 000000000..d159f6054 --- /dev/null +++ b/docs/library/authentication.rst @@ -0,0 +1,5 @@ +:mod:`authentication` +===================== + +.. automodule:: authentication + :members: diff --git a/docs/library/authenticators.rst b/docs/library/authenticators.rst deleted file mode 100644 index 407339f78..000000000 --- a/docs/library/authenticators.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`authenticators` -===================== - -.. automodule:: authenticators - :members: diff --git a/docs/library/emitters.rst b/docs/library/emitters.rst deleted file mode 100644 index 590ace0fa..000000000 --- a/docs/library/emitters.rst +++ /dev/null @@ -1,7 +0,0 @@ -:mod:`emitters` -=============== - -The emitters module provides a set of emitters that can be plugged in to a :class:`.Resource`. An emitter is responsible for taking the output of a and serializing it to a given media type. A :class:`.Resource` can have a number of emitters, allow the same content to be serialized in a number of different formats depending on the requesting client's preferences, as specified in the HTTP Request's Accept header. - -.. automodule:: emitters - :members: diff --git a/docs/library/modelresource.rst b/docs/library/modelresource.rst deleted file mode 100644 index af7609442..000000000 --- a/docs/library/modelresource.rst +++ /dev/null @@ -1,9 +0,0 @@ -:mod:`modelresource` -==================== - -.. note:: - - TODO - document this module properly - -.. automodule:: modelresource - :members: diff --git a/docs/library/renderers.rst b/docs/library/renderers.rst new file mode 100644 index 000000000..a9e729316 --- /dev/null +++ b/docs/library/renderers.rst @@ -0,0 +1,10 @@ +:mod:`renderers` +================ + +The renderers module provides a set of renderers that can be plugged in to a :class:`.Resource`. +A renderer is responsible for taking the output of a View and serializing it to a given media type. +A :class:`.Resource` can have a number of renderers, allow the same content to be serialized in a number +of different formats depending on the requesting client's preferences, as specified in the HTTP Request's Accept header. + +.. automodule:: renderers + :members: From 66b9bda9bf9492c5e1ffba162e044aacb51bbd7e Mon Sep 17 00:00:00 2001 From: markotibold Date: Tue, 17 May 2011 00:18:45 +0200 Subject: [PATCH 2/3] All top level modules are included. Ready for diving into the modules and documenting/ enhancing already existing docs. --- djangorestframework/views.py | 6 +----- docs/index.rst | 12 ++++++++---- docs/library/compat.rst | 5 +++++ docs/library/mixins.rst | 5 +++++ docs/library/permissions.rst | 5 +++++ docs/library/views.rst | 5 +++++ 6 files changed, 29 insertions(+), 9 deletions(-) create mode 100644 docs/library/compat.rst create mode 100644 docs/library/mixins.rst create mode 100644 docs/library/permissions.rst create mode 100644 docs/library/views.rst diff --git a/djangorestframework/views.py b/djangorestframework/views.py index 2e7e8418a..81567e687 100644 --- a/djangorestframework/views.py +++ b/djangorestframework/views.py @@ -11,7 +11,7 @@ __all__ = ( 'BaseView', 'ModelView', 'InstanceModelView', - 'ListOrModelView', + 'ListModelView', 'ListOrCreateModelView' ) @@ -131,7 +131,3 @@ class ListModelView(ListModelMixin, ModelView): class ListOrCreateModelView(ListModelMixin, CreateModelMixin, ModelView): """A view which provides default operations for list and create, against a model in the database.""" pass - - - - diff --git a/docs/index.rst b/docs/index.rst index fac1c94bc..75569d457 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -140,13 +140,17 @@ Library Reference .. toctree:: :maxdepth: 1 - library/resource - library/renderers - library/parsers library/authentication - library/validators + library/compat + library/mixins + library/parsers + library/permissions + library/renderers + library/resource library/response library/status + library/validators + library/views Examples Reference ------------------ diff --git a/docs/library/compat.rst b/docs/library/compat.rst new file mode 100644 index 000000000..93fb081a0 --- /dev/null +++ b/docs/library/compat.rst @@ -0,0 +1,5 @@ +:mod:`compat` +===================== + +.. automodule:: compat + :members: diff --git a/docs/library/mixins.rst b/docs/library/mixins.rst new file mode 100644 index 000000000..04bf66b06 --- /dev/null +++ b/docs/library/mixins.rst @@ -0,0 +1,5 @@ +:mod:`mixins` +===================== + +.. automodule:: mixins + :members: diff --git a/docs/library/permissions.rst b/docs/library/permissions.rst new file mode 100644 index 000000000..c694d639a --- /dev/null +++ b/docs/library/permissions.rst @@ -0,0 +1,5 @@ +:mod:`permissions` +===================== + +.. automodule:: permissions + :members: diff --git a/docs/library/views.rst b/docs/library/views.rst new file mode 100644 index 000000000..329b487b7 --- /dev/null +++ b/docs/library/views.rst @@ -0,0 +1,5 @@ +:mod:`views` +===================== + +.. automodule:: views + :members: From 40573b2793a49d68b89ea5b6c4bff0e13470cc0c Mon Sep 17 00:00:00 2001 From: markotibold Date: Tue, 17 May 2011 01:27:27 +0200 Subject: [PATCH 3/3] Nicely marked up source code. --- djangorestframework/authentication.py | 31 +++++++++++++++------------ 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/djangorestframework/authentication.py b/djangorestframework/authentication.py index b0ba41aae..e3e44ffbe 100644 --- a/djangorestframework/authentication.py +++ b/djangorestframework/authentication.py @@ -1,10 +1,10 @@ """ -The ``authentication`` module provides a set of pluggable authentication classes. +The :mod:`authentication` module provides a set of pluggable authentication classes. -Authentication behavior is provided by adding the ``AuthMixin`` class to a ``View`` . +Authentication behavior is provided by mixing the :class:`mixins.AuthMixin` class into a :class:`View` class. The set of authentication methods which are used is then specified by setting the -``authentication`` attribute on the ``View`` class, and listing a set of authentication classes. +:attr:`authentication` attribute on the :class:`View` class, and listing a set of authentication classes. """ from django.contrib.auth import authenticate @@ -22,28 +22,31 @@ __all__ = ( class BaseAuthenticaton(object): """ All authentication classes should extend BaseAuthentication. + + :param view: :class:`Authentication` classes are always passed the current view on creation. """ def __init__(self, view): """ - Authentication classes are always passed the current view on creation. """ self.view = view def authenticate(self, request): """ - Authenticate the request and return a ``User`` instance or None. (*) + :param request: Request to be authenticated + :rtype: :obj:`User` object or None [*]_ - This function must be overridden to be implemented. + .. Note:: + This function must be overridden to be implemented. - (*) The authentication context _will_ typically be a ``User`` object, - but it need not be. It can be any user-like object so long as the - permissions classes on the view can handle the object and use - it to determine if the request has the required permissions or not. - - This can be an important distinction if you're implementing some token - based authentication mechanism, where the authentication context - may be more involved than simply mapping to a ``User``. + .. [*] The authentication context *will* typically be a :obj:`User` object, + but it need not be. It can be any user-like object so long as the + permissions classes on the view can handle the object and use + it to determine if the request has the required permissions or not. + + This can be an important distinction if you're implementing some token + based authentication mechanism, where the authentication context + may be more involved than simply mapping to a :obj:`User`. """ return None