Make docstring parser more flexible

[costrouc]

This is an issue to judge interest in making the parser for docstrings more flexible (I will create a PR if so). Currently it looks like everything past --- is interpreted as a swagger specification for a route. I would like to create a PR for a docstring_handler function that can parse a given docstring and return the dict of the yaml specification. In my case I am using numpy docstring style https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html and the --- conflicts with the documentation syntax. I would like to add a docstring_handler to can parse a specification like so.

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Route
    --------
    
    .. code-block:: yaml
 
              summary: Adds a new user
                requestBody:
                  content:
                    application/json:
                      schema:      # Request body contents
                        type: object
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                        example:   # Sample object
                          id: 10
                          name: Jessica Smith
                responses:
                  '200':
                    description: OK

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """
    pass

This docstring_handler would return

summary: Adds a new user
  requestBody:
    content:
      application/json:
        schema:      # Request body contents
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
          example:   # Sample object
            id: 10
            name: Jessica Smith
  responses:
    '200':
      description: OK