improve documentation, remove py2 wheel tag, mark as mypy-enabled

MANIFEST.in

@@ -1,5 +1,6 @@
 include *.rst
 include LICENSE
+include drf_spectacular/py.typed
 include drf_spectacular/validation/*.json
 include drf_spectacular/templates/drf_spectacular/*.html
 include drf_spectacular/templates/drf_spectacular/*.js

drf_spectacular/utils.py

@@ -70,12 +70,13 @@ class OpenApiSchemaBase:
 
 class OpenApiExample(OpenApiSchemaBase):
     """
-    https://swagger.io/specification/
-     * Specification
-        * Schema
-           * ExampleObject
-    """
+    Helper class to document a API parameter / request body / response body
+    with a concrete example value.
 
+    The example will be attached to the operation object where appropriate,
+    i. e. where the given ``media_type``, ``status_code`` and modifiers match.
+    Example that do not match any scenario are ignored.
+    """
     def __init__(
             self,
             name: str,
@@ -100,6 +101,16 @@ def __init__(
 
 
 class OpenApiParameter(OpenApiSchemaBase):
+    """
+    Helper class to document request query/path/header/cookie parameters.
+    Can also be used to document response headers.
+
+    Please note that not all arguments apply to all ``location``/``type``/direction
+    variations, e.g. path parameters are ``required=True`` by definition.
+
+    For valid ``style`` choices please consult the
+    `OpenAPI specification <https://swagger.io/specification/#style-values>`_.
+    """
     QUERY = 'query'
     PATH = 'path'
     HEADER = 'header'
@@ -140,7 +151,10 @@ class OpenApiResponse(OpenApiSchemaBase):
     """
     Helper class to bundle a response object (``Serializer``, ``OpenApiType``,
     raw schema, etc) together with a response object description and/or examples.
-    Examples can alternatively be provided via @extend_schema.
+    Examples can alternatively be provided via :func:`@extend_schema <.extend_schema>`.
+
+    This class is especially helpful for explicitly describing status codes on a
+    "Response Object" level.
     """
     def __init__(
             self,
@@ -170,8 +184,8 @@ def extend_schema(
         examples: Optional[List[OpenApiExample]] = None,
 ):
     """
-    decorator mainly for the "view" method kind. partially or completely overrides
-    what would be generated by drf-spectacular.
+    Decorator mainly for the "view" method kind. Partially or completely overrides
+    what would be otherwise generated by drf-spectacular.
 
     :param operation_id: replaces the auto-generated operation_id. make sure there
         are no naming collisions.
@@ -368,7 +382,7 @@ def extend_schema_serializer(
 ):
     """
     Decorator for the "serializer" kind. Intended for overriding default serializer behaviour that
-    cannot be influenced through `.extend_schema`.
+    cannot be influenced through :func:`@extend_schema <.extend_schema>`.
 
     :param many: override how serializer is initialized. Mainly used to coerce the list view detection
         heuristic to acknowledge a non-list serializer.
@@ -393,9 +407,13 @@ def extend_schema_view(**kwargs):
     Convenience decorator for the "view" kind. Intended for annotating derived view methods that
     are are not directly present in the view (usually methods like ``list`` or ``retrieve``).
     Spares you from overriding methods like ``list``, only to perform a super call in the body
-    so that you have have something to attach ``@extend_schema`` to.
+    so that you have have something to attach :func:`@extend_schema <.extend_schema>` to.
+
+    This decorator also takes care of safely attaching annotations to derived view methods,
+    preventing leakage into unrelated views.
 
-    :param kwargs: method names as argument names and ``extend_schema()`` calls as values
+    :param kwargs: method names as argument names and :func:`@extend_schema <.extend_schema>`
+      calls as values
     """
     def wrapping_decorator(method_decorator, method):
         @method_decorator
@@ -431,8 +449,9 @@ def decorator(view):
 
 def inline_serializer(name: str, fields: Dict[str, Field], **kwargs) -> Serializer:
     """
-    A helper function to create an inline serializer. Primary use is with `@extend_schema`,
-    where one needs an implicit one-off serializer that is not reflected in an actual class.
+    A helper function to create an inline serializer. Primary use is with
+    :func:`@extend_schema <.extend_schema>`, where one needs an implicit one-off
+    serializer that is not reflected in an actual class.
 
     :param name: name of the
     :param fields: dict with field names as keys and serializer fields as values

tests/test_regressions.py

@@ -1636,7 +1636,7 @@ class XSerializer(serializers.Serializer):
         custom_field = CustomField()
 
         def get_method_field(self, obj) -> typing.Any:
-            return
+            return  # pragma: no cover
 
     @extend_schema(request=typing.Any, responses=XSerializer)
     @api_view(['POST'])
@@ -1769,6 +1769,7 @@ class XViewset(viewsets.ModelViewSet):
             'description': 'a list that actually returns numbers'
         }
     }
+    assert schema['paths']['/x/']['post']['description'] == 'creation description'
     assert schema['paths']['/x/']['post']['responses'] == {
         '201': {
             'content': {'application/json': {'schema': {'type': 'integer'}}},