diff options
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/2.3-announcement.md | 6 | ||||
| -rw-r--r-- | docs/topics/ajax-csrf-cors.md | 2 | ||||
| -rw-r--r-- | docs/topics/browsable-api.md | 22 | ||||
| -rw-r--r-- | docs/topics/browser-enhancements.md | 2 | ||||
| -rw-r--r-- | docs/topics/contributing.md | 5 | ||||
| -rw-r--r-- | docs/topics/release-notes.md | 2 | ||||
| -rw-r--r-- | docs/topics/rest-framework-2-announcement.md | 6 | ||||
| -rw-r--r-- | docs/topics/rest-hypermedia-hateoas.md | 2 |
8 files changed, 24 insertions, 23 deletions
diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md index d51037b7..9fdebcd9 100644 --- a/docs/topics/2.3-announcement.md +++ b/docs/topics/2.3-announcement.md @@ -45,7 +45,7 @@ The best place to get started with ViewSets and Routers is to take a look at the ## Simpler views -This release rationalises the API and implementation of the generic views, dropping the dependancy on Django's `SingleObjectMixin` and `MultipleObjectMixin` classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with. +This release rationalises the API and implementation of the generic views, dropping the dependency on Django's `SingleObjectMixin` and `MultipleObjectMixin` classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with. This improvement is reflected in improved documentation for the `GenericAPIView` base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses. @@ -108,7 +108,7 @@ Using the `SingleObjectAPIView` and `MultipleObjectAPIView` base classes continu ### Removed attributes -The following attributes and methods, were previously present as part of Django's generic view implementations, but were unneeded and unusedand have now been entirely removed. +The following attributes and methods, were previously present as part of Django's generic view implementations, but were unneeded and unused and have now been entirely removed. * context_object_name * get_context_data() @@ -173,7 +173,7 @@ For example: raise Http404 return queryset -In our opinion removing lesser-used attributes like `allow_empty` helps us move towards simpler generic view implementations, making them more obvious to use and override, and re-inforcing the preferred style of developers writing their own base classes and mixins for custom behavior rather than relying on the configurability of the generic views. +In our opinion removing lesser-used attributes like `allow_empty` helps us move towards simpler generic view implementations, making them more obvious to use and override, and re-enforcing the preferred style of developers writing their own base classes and mixins for custom behavior rather than relying on the configurability of the generic views. ## Simpler URL lookups diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md index f7d12940..4566f38b 100644 --- a/docs/topics/ajax-csrf-cors.md +++ b/docs/topics/ajax-csrf-cors.md @@ -1,6 +1,6 @@ # Working with AJAX, CSRF & CORS -> "Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability — very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one." +> "Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability — very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one." > > — [Jeff Atwood][cite] diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 65f76abc..dcba9b0a 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -1,20 +1,20 @@ # The Browsable API -> It is a profoundly erroneous truism... that we should cultivate the habit of thinking of what we are doing. The precise opposite is the case. Civilization advances by extending the number of important operations which we can perform without thinking about them. +> It is a profoundly erroneous truism... that we should cultivate the habit of thinking of what we are doing. The precise opposite is the case. Civilization advances by extending the number of important operations which we can perform without thinking about them. > > — [Alfred North Whitehead][cite], An Introduction to Mathematics (1911) -API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. +API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. ## URLs -If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `rest_framework` package includes a [`reverse`][drfreverse] helper for this purpose. +If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `rest_framework` package includes a [`reverse`][drfreverse] helper for this purpose. ## Formats -By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox][ffjsonview] and [Chrome][chromejsonview]. +By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox][ffjsonview] and [Chrome][chromejsonview]. ## Customizing @@ -25,15 +25,15 @@ The included browsable API template is built with [Bootstrap (2.1.1)][bootstrap] ### Theme -To replace the theme wholesale, add a `bootstrap_theme` block to your `api.html` and insert a `link` to the desired Bootstrap theme css file. This will completely replace the included theme. +To replace the theme wholesale, add a `bootstrap_theme` block to your `api.html` and insert a `link` to the desired Bootstrap theme css file. This will completely replace the included theme. {% block bootstrap_theme %} <link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css"> {% endblock %} -A suitable replacement theme can be generated using Bootstrap's [Customize Tool][bcustomize]. Also, there are pre-made themes available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. +A suitable replacement theme can be generated using Bootstrap's [Customize Tool][bcustomize]. Also, there are pre-made themes available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. -You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style. +You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style. Full Example @@ -57,11 +57,11 @@ All of the blocks available in the browsable API base template that can be used * `bootstrap_theme` - CSS for the Bootstrap theme * `bootstrap_navbar_variant` - CSS class for the navbar * `branding` - section of the navbar, see [Bootstrap components][bcomponentsnav] -* `breadcrumbs` - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block. +* `breadcrumbs` - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block. * `footer` - Any copyright notices or similar footer materials can go here (by default right-aligned) * `style` - CSS stylesheets for the page * `title` - title of the page -* `userlinks` - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use {{ block.super }} to preserve the authentication links. +* `userlinks` - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use {{ block.super }} to preserve the authentication links. #### Components @@ -69,7 +69,7 @@ All of the [Bootstrap components][bcomponents] are available. ##### Tooltips -The browsable API makes use of the Bootstrap tooltips component. Any element with the `js-tooltip` class and a `title` attribute has that title content displayed in a tooltip on hover after a 1000ms delay. +The browsable API makes use of the Bootstrap tooltips component. Any element with the `js-tooltip` class and a `title` attribute has that title content displayed in a tooltip on hover after a 1000ms delay. ### Login Template @@ -107,7 +107,7 @@ The context that's available to the template: #### Not using base.html -For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you. +For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you. [cite]: http://en.wikiquote.org/wiki/Alfred_North_Whitehead [drfreverse]: ../api-guide/reverse.md diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index 31b94841..5a172620 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -21,7 +21,7 @@ For example, given the following form: ## HTTP header based method overriding -REST framework also supports method overriding via the semi-standard `X-HTTP-Method-Override` header. This can be useful if you are working with non-form content such as JSON and are working with an older web server and/or hosting provider that doesn't recognise particular HTTP methods such as `PATCH`. For example [Amazon Web Services ELB][aws_elb]. +REST framework also supports method overriding via the semi-standard `X-HTTP-Method-Override` header. This can be useful if you are working with non-form content such as JSON and are working with an older web server and/or hosting provider that doesn't recognise particular HTTP methods such as `PATCH`. For example [Amazon Web Services ELB][aws_elb]. To use it, make a `POST` request, setting the `X-HTTP-Method-Override` header. diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index fd60daea..123e4a8a 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -1,6 +1,6 @@ # Contributing to REST framework -> The world can only really be changed one piece at a time. The art is picking that piece. +> The world can only really be changed one piece at a time. The art is picking that piece. > > — [Tim Berners-Lee][cite] @@ -24,7 +24,7 @@ Some tips on good issue reporting: * When describing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. * Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. -* If reporting a bug, then try to include a pull request with a failing test case. This will help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one. +* If reporting a bug, then try to include a pull request with a failing test case. This will help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one. @@ -32,6 +32,7 @@ Some tips on good issue reporting: # Development + * git clone & PYTHONPATH * Pep8 * Recommend editor that runs pep8 diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 16ac961d..fb14cf5f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -225,7 +225,7 @@ The security vulnerabilities only affect APIs which use the `XMLParser` class, b * Bugfix: Validation errors instead of exceptions when related fields receive incorrect types. * Bugfix: Handle ObjectDoesNotExist exception when serializing null reverse one-to-one -**Note**: Prior to 2.1.16, The Decimals would render in JSON using floating point if `simplejson` was installed, but otherwise render using string notation. Now that use of `simplejson` has been deprecated, Decimals will consistently render using string notation. See [#582] for more details. +**Note**: Prior to 2.1.16, The Decimals would render in JSON using floating point if `simplejson` was installed, but otherwise render using string notation. Now that use of `simplejson` has been deprecated, Decimals will consistently render using string notation. See [#582] for more details. ### 2.1.15 diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index c527937f..f1060d90 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -2,7 +2,7 @@ What it is, and why you should care. -> Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. +> Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. > > — [Roy Fielding][cite] @@ -22,9 +22,9 @@ This article is intended to give you a flavor of what REST framework 2 is, and w Before we get cracking, let's start with the hard sell, with a few bits of feedback from some early adopters… -"Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz." - [Kit La Touche][quote1] +"Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz." - [Kit La Touche][quote1] -"Since it's pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2] has definitely got the right approach here; even simple things like being able to override a function called post to do custom work during rather than having to intimately know what happens during a post make a huge difference to your productivity." - [Ian Strachan][quote2] +"Since it's pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2] has definitely got the right approach here; even simple things like being able to override a function called post to do custom work during rather than having to intimately know what happens during a post make a huge difference to your productivity." - [Ian Strachan][quote2] "I switched to the 2.0 branch and I don't regret it - fully refactored my code in another ½ day and it's *much* more to my tastes" - [Bruno Desthuilliers][quote3] diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index aeba579f..b4899a36 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -1,6 +1,6 @@ # REST, Hypermedia & HATEOAS -> You keep using that word "REST". I do not think it means what you think it means. +> You keep using that word "REST". I do not think it means what you think it means. > > — Mike Amundsen, [REST fest 2012 keynote][cite]. |