Parse views docstrings for summary/description

[lafrech]

Following up on a discussion in flask-rest-api: marshmallow-code/flask-smorest#3.

A contributor suggested to parse the docstrings for summary. I think we can go further and also get description:

def my_view(...):
"""Summary

Long description...
"""

This could be done in apispec and it is compatible with the YAML docstring parsing:

def my_view(...):
"""Summary

Long description...
---
YAML stuff
"""

I didn't take much time to look into it any deeper.

Marking as 1.0 as I would like to at least take needed utils out of yaml_utils.py (trim_docstring, maybe dedent) back into utils (those have no yaml dependency).

Marking as backward incompatible in case the feature is activated by default.

[lafrech]

On second thought, apispec does not need this as summary and description are passed in the YAML section. My bad.

Yet, I'd still like to do this before 1.0:

Marking as 1.0 as I would like to at least take needed utils out of yaml_utils.py (trim_docstring, maybe dedent) back into utils (those have no yaml dependency).

[lafrech]

Closing in favor of #262. Sorry for the noise.