Improve RTD documentation

[tfranzel]

There have been a lot of feature additions recently. Some work silently in the background, other don't. Someone coming onboard now might have a hard time using some of the more advanced features.

• Make it easier to adopt drf-spectacular
• Make transition from drf-yasg easier. some feature basically do the same with a different name.
• Make it easier to solve common issues.
• Explain the usage of @extend_schema(|_fields|_serializer), Extensions and hooks and their mechanics.

[MissiaL]

I would also add helper decorators for drf_yasg which proxied requests in extend_scema

swagger_auto_schema should be convert to extend_schema

from drf_spectacular.utils.helpers import swagger_auto_schema, ...

I think this is an interesting idea

[tfranzel]

that is a excellent idea, but it is probably impractical.

we support a sub-/super-set of the yasg features, e.g. no inspectors. we do have methods, manual_parameters, responses, operation_id, request_body, some of which might work 1to1 and other don't. so i believe its brittle to support this transparently. people will need to change their swagger_auto_schema calls. likely no way around it. on the bright side it is mostly a trivial change.

def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_body=None, query_serializer=None,
                        manual_parameters=None, operation_id=None, operation_description=None, operation_summary=None,
                        security=None, deprecated=None, responses=None, field_inspectors=None, filter_inspectors=None,
                        paginator_inspectors=None, tags=None, **extra_overrides):

also i don't want to maintain a bridge layer or add functionality we have not needed yet just for the sake of decorator compatibility.