From 7ff1facd53515318aa355144a2d61e0e429e517e Mon Sep 17 00:00:00 2001 From: Shyamkumar Yadav Date: Sat, 8 Oct 2022 17:46:17 +0530 Subject: [PATCH] docs: lint --- docs/community/3.0-announcement.md | 5 +- docs/community/3.1-announcement.md | 4 +- docs/community/3.10-announcement.md | 38 ++--- docs/community/3.11-announcement.md | 42 +++-- docs/community/3.12-announcement.md | 89 ++++++----- docs/community/3.13-announcement.md | 8 +- docs/community/3.14-announcement.md | 1 - docs/community/3.3-announcement.md | 2 +- docs/community/3.5-announcement.md | 22 ++- docs/community/3.8-announcement.md | 3 - docs/community/3.9-announcement.md | 57 +++---- .../coreapi/7-schemas-and-client-libraries.md | 14 +- docs/coreapi/from-documenting-your-api.md | 16 +- docs/index.md | 3 - docs/topics/ajax-csrf-cors.md | 2 +- docs/topics/browsable-api.md | 1 - docs/topics/documenting-your-api.md | 147 ++++++++---------- docs/topics/html-and-forms.md | 63 ++++++-- docs/topics/writable-nested-serializers.md | 5 +- docs/tutorial/quickstart.md | 2 +- 20 files changed, 261 insertions(+), 263 deletions(-) diff --git a/docs/community/3.0-announcement.md b/docs/community/3.0-announcement.md index b9461defe..22a0d9aec 100644 --- a/docs/community/3.0-announcement.md +++ b/docs/community/3.0-announcement.md @@ -58,7 +58,6 @@ Instead of passing the files argument separately: # Don't do this... ExampleSerializer(data=request.DATA, files=request.FILES) - The usage of `request.QUERY_PARAMS` is now pending deprecation in favor of the lowercased `request.query_params`. --- @@ -791,7 +790,7 @@ Both styles "`PUT` as 404" and "`PUT` as create" can be valid in different circu If you need to restore the previous behavior you may want to include [this `AllowPUTAsCreateMixin` class](https://gist.github.com/tomchristie/a2ace4577eff2c603b1b) as a mixin to your views. -#### Customizing error responses. +#### Customizing error responses. The generic views now raise `ValidationFailed` exception for invalid data. This exception is then dealt with by the exception handler, rather than the view returning a `400 Bad Request` response directly. @@ -807,7 +806,7 @@ This makes it far easier to use a different style for `OPTIONS` responses throug --- -## Serializers as HTML forms +## Serializers as HTML forms REST framework 3.0 includes templated HTML form rendering for serializers. diff --git a/docs/community/3.1-announcement.md b/docs/community/3.1-announcement.md index 641f313d0..005f58f5d 100644 --- a/docs/community/3.1-announcement.md +++ b/docs/community/3.1-announcement.md @@ -129,7 +129,7 @@ Many thanks to [Craig Blaszczyk](https://github.com/jakul) for helping push this --- -## New field types +## New field types Django 1.8's new `ArrayField`, `HStoreField` and `UUIDField` are now all fully supported. @@ -192,7 +192,7 @@ All these attributes and options will still work in 3.1, but their usage will ra --- -## What's next? +## What's next? The next focus will be on HTML renderings of API output and will include: diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md index 19748aa40..ceb37c630 100644 --- a/docs/community/3.10-announcement.md +++ b/docs/community/3.10-announcement.md @@ -39,12 +39,10 @@ update your REST framework settings to include `DEFAULT_SCHEMA_CLASS` explicitly **settings.py**: -```python -REST_FRAMEWORK = { - ... - 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' -} -``` + REST_FRAMEWORK = { + ... + 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' + } You'll still be able to keep using CoreAPI schemas, API docs, and client for the foreseeable future. We'll aim to ensure that the CoreAPI schema generator remains @@ -54,7 +52,7 @@ from REST framework, scheduled for version 3.12. We have removed the old documentation for the CoreAPI based schema generation. You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs]. ----- +--- ## OpenAPI Quickstart @@ -66,21 +64,19 @@ shortcut. In your `urls.py`: -```python -from rest_framework.schemas import get_schema_view + from rest_framework.schemas import get_schema_view -urlpatterns = [ - # ... - # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs. - # * `title` and `description` parameters are passed to `SchemaGenerator`. - # * Provide view name for use with `reverse()`. - path('openapi', get_schema_view( - title="Your Project", - description="API for all things …" - ), name='openapi-schema'), - # ... -] -``` + urlpatterns = [ + # ... + # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs. + # * `title` and `description` parameters are passed to `SchemaGenerator`. + # * Provide view name for use with `reverse()`. + path('openapi', get_schema_view( + title="Your Project", + description="API for all things …" + ), name='openapi-schema'), + # ... + ] ### Customization diff --git a/docs/community/3.11-announcement.md b/docs/community/3.11-announcement.md index 83dd636d1..3a9ce97b3 100644 --- a/docs/community/3.11-announcement.md +++ b/docs/community/3.11-announcement.md @@ -41,20 +41,18 @@ include: In this example view operation descriptions for the `get` and `post` methods will be extracted from the class docstring: -```python -class DocStringExampleListView(APIView): -""" -get: A description of my GET operation. -post: A description of my POST operation. -""" - permission_classes = [permissions.IsAuthenticatedOrReadOnly] + class DocStringExampleListView(APIView): + """ + get: A description of my GET operation. + post: A description of my POST operation. + """ + permission_classes = [permissions.IsAuthenticatedOrReadOnly] - def get(self, request, *args, **kwargs): - ... + def get(self, request, *args, **kwargs): + ... - def post(self, request, *args, **kwargs): - ... -``` + def post(self, request, *args, **kwargs): + ... ## Validator / Default Context @@ -71,23 +69,19 @@ The `__call__` method should then include an additional `serializer_field` argum Validator implementations will look like this: -```python -class CustomValidator: - requires_context = True + class CustomValidator: + requires_context = True - def __call__(self, value, serializer_field): - ... -``` + def __call__(self, value, serializer_field): + ... Default implementations will look like this: -```python -class CustomDefault: - requires_context = True + class CustomDefault: + requires_context = True - def __call__(self, serializer_field): - ... -``` + def __call__(self, serializer_field): + ... --- diff --git a/docs/community/3.12-announcement.md b/docs/community/3.12-announcement.md index 9d2220933..221a09e69 100644 --- a/docs/community/3.12-announcement.md +++ b/docs/community/3.12-announcement.md @@ -30,20 +30,39 @@ in the URL path. For example... -Method | Path | Tags ---------------------------------|-----------------|------------- -`GET`, `PUT`, `PATCH`, `DELETE` | `/users/{id}/` | `['users']` -`GET`, `POST` | `/users/` | `['users']` -`GET`, `PUT`, `PATCH`, `DELETE` | `/orders/{id}/` | `['orders']` -`GET`, `POST` | `/orders/` | `['orders']` + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodPathTags
GET, PUT, PATCH, DELETE/users/{id}/['users']
GET, POST/users/['users']
GET, PUT, PATCH, DELETE/orders/{id}/['orders']
GET, POST/orders/['orders']
The tags used for a particular view may also be overridden... -```python -class MyOrders(APIView): - schema = AutoSchema(tags=['users', 'orders']) - ... -``` + class MyOrders(APIView): + schema = AutoSchema(tags=['users', 'orders']) + ... See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags) for more information. @@ -66,10 +85,8 @@ The names used for a component default to using the serializer class name, [but may be overridden if needed](https://www.django-rest-framework.org/api-guide/schemas/#components )... -```python -class MyOrders(APIView): - schema = AutoSchema(component_name="OrderDetails") -``` + class MyOrders(APIView): + schema = AutoSchema(component_name="OrderDetails") ## More Public API @@ -111,35 +128,31 @@ The class now supports nested search within `JSONField` and `HStoreField`, using the double underscore notation for traversing which element of the field the search should apply to. -```python -class SitesSearchView(generics.ListAPIView): - """ - An API view to return a list of archaeological sites, optionally filtered - by a search against the site name or location. (Location searches are - matched against the region and country names.) - """ - queryset = Sites.objects.all() - serializer_class = SitesSerializer - filter_backends = [filters.SearchFilter] - search_fields = ['site_name', 'location__region', 'location__country'] -``` + class SitesSearchView(generics.ListAPIView): + """ + An API view to return a list of archaeological sites, optionally filtered + by a search against the site name or location. (Location searches are + matched against the region and country names.) + """ + queryset = Sites.objects.all() + serializer_class = SitesSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['site_name', 'location__region', 'location__country'] ### Searches against annotate fields Django allows querysets to create additional virtual fields, using the `.annotate` method. We now support searching against annotate fields. -```python -class PublisherSearchView(generics.ListAPIView): - """ - Search for publishers, optionally filtering the search against the average - rating of all their books. - """ - queryset = Publisher.objects.annotate(avg_rating=Avg('book__rating')) - serializer_class = PublisherSerializer - filter_backends = [filters.SearchFilter] - search_fields = ['avg_rating'] -``` + class PublisherSearchView(generics.ListAPIView): + """ + Search for publishers, optionally filtering the search against the average + rating of all their books. + """ + queryset = Publisher.objects.annotate(avg_rating=Avg('book__rating')) + serializer_class = PublisherSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['avg_rating'] --- diff --git a/docs/community/3.13-announcement.md b/docs/community/3.13-announcement.md index e2c1fefa6..ccaed4e3e 100644 --- a/docs/community/3.13-announcement.md +++ b/docs/community/3.13-announcement.md @@ -40,15 +40,11 @@ From REST framework 3.13 onwards, this is now *explicitly enforced*. The most feasible cases where users might be accidentally omitting the keyword arguments are likely in the composite fields, `ListField` and `DictField`. For instance... -```python -aliases = serializers.ListField(serializers.CharField()) -``` + aliases = serializers.ListField(serializers.CharField()) They must now use the more explicit keyword argument style... -```python -aliases = serializers.ListField(child=serializers.CharField()) -``` + aliases = serializers.ListField(child=serializers.CharField()) This change has been made because using positional arguments here *does not* result in the expected behaviour. diff --git a/docs/community/3.14-announcement.md b/docs/community/3.14-announcement.md index 0543d0d6d..819eb1d65 100644 --- a/docs/community/3.14-announcement.md +++ b/docs/community/3.14-announcement.md @@ -44,7 +44,6 @@ skipped depending on the other arguments. See Pull Request [#7574](https://github.com/encode/django-rest-framework/pull/7574) for more details. - ## Make Open API `get_reference` public. Returns a reference to the serializer component. This may be useful if you override `get_schema()`. diff --git a/docs/community/3.3-announcement.md b/docs/community/3.3-announcement.md index 5dcbe3b3b..24f493dcd 100644 --- a/docs/community/3.3-announcement.md +++ b/docs/community/3.3-announcement.md @@ -38,7 +38,7 @@ The AJAX based support for the browsable API means that there are a number of in * To support form based `PUT` and `DELETE`, or to support form content types such as JSON, you should now use the [AJAX forms][ajax-form] javascript library. This replaces the previous 'method and content type overloading' that required significant internal complexity to the request class. * The `accept` query parameter is no longer supported by the default content negotiation class. If you require it then you'll need to [use a custom content negotiation class][accept-headers]. -* The custom `HTTP_X_HTTP_METHOD_OVERRIDE` header is no longer supported by default. If you require it then you'll need to [use custom middleware][method-override]. +* The custom `HTTP_X_HTTP_METHOD_OVERRIDE` header is no longer supported by default. If you require it then you'll need to [use custom middleware][method-override]. The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly deprecated, and has now been removed entirely, in line with the deprecation policy. diff --git a/docs/community/3.5-announcement.md b/docs/community/3.5-announcement.md index 91bfce428..cf6f50ee4 100644 --- a/docs/community/3.5-announcement.md +++ b/docs/community/3.5-announcement.md @@ -59,20 +59,18 @@ For example, to include a swagger schema to your API, you would do the following * Include the schema view in your URL conf: -```py -from rest_framework.schemas import get_schema_view -from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer + from rest_framework.schemas import get_schema_view + from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer -schema_view = get_schema_view( - title='Example API', - renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer] -) + schema_view = get_schema_view( + title='Example API', + renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer] + ) -urlpatterns = [ - path('swagger/', schema_view), - ... -] -``` + urlpatterns = [ + path('swagger/', schema_view), + ... + ] There have been a large number of fixes to the schema generation. These should resolve issues for anyone using the latest version of the `django-rest-swagger` diff --git a/docs/community/3.8-announcement.md b/docs/community/3.8-announcement.md index 507299782..c6e1ed306 100644 --- a/docs/community/3.8-announcement.md +++ b/docs/community/3.8-announcement.md @@ -29,7 +29,6 @@ the foundations for future changes. If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by **[signing up for a paid plan][funding]**. - *We'd like to say thanks in particular our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://machinalis.com/), and [Rollbar](https://rollbar.com).* --- @@ -68,7 +67,6 @@ The new `action` decorator takes a boolean `detail` argument. * Replace `detail_route` uses with `@action(detail=True)`. * Replace `list_route` uses with `@action(detail=False)`. - ### `exclude_from_schema` Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` decorator are now deprecated. They will be removed entirely in 3.9. @@ -84,7 +82,6 @@ For function based views the `@schema` decorator can be used to exclude the view There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page for a complete listing. - ## What's next We're currently working towards moving to using [OpenAPI][openapi] as our default schema output. We'll also be revisiting our API documentation generation and client libraries. diff --git a/docs/community/3.9-announcement.md b/docs/community/3.9-announcement.md index d673fdd18..2fbb60b2a 100644 --- a/docs/community/3.9-announcement.md +++ b/docs/community/3.9-announcement.md @@ -19,7 +19,7 @@ # Django REST framework 3.9 -The 3.9 release gives access to _extra actions_ in the Browsable API, introduces composable permissions and built-in [OpenAPI][openapi] schema support. (Formerly known as Swagger) +The 3.9 release gives access to *extra actions* in the Browsable API, introduces composable permissions and built-in [OpenAPI][openapi] schema support. (Formerly known as Swagger) --- @@ -28,7 +28,6 @@ The 3.9 release gives access to _extra actions_ in the Browsable API, introduces If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by **[signing up for a paid plan][funding]**. -