'Examines a controller for documentation.  A dictionary index of
sections containing dictionaries of URLs is returned.  For each URL, a
dictionary of HTTP methods (GET, POST, etc.) is contained.  For each
URL/method pair, a dictionary containing the following items is
available:
- `doc`: Markdown-formatted docstring.
- `uri`: Manually-specified URI to list the API method as
- `uri_variants`: Alternate URIs to access the API method from
- `supports_rss`: Indicates the URI also supports rss consumption
- `parameters`: Dictionary of possible parameter names and descriptions.
- `extends`: API method from which to inherit documentation
- `json_model`: The JSON model used instead of normal POST parameters'

@staticmethod
def docs_from_controller(controller, url_prefix='/api', oauth_only=False):

    api_docs = defaultdict((lambda : defaultdict(dict)))
    for (name, func) in controller.__dict__.iteritems():
        (method, sep, action) = name.partition('_')
        if (not action):
            continue
        valid_methods = ('GET', 'POST', 'PUT', 'DELETE', 'PATCH')
        api_doc = getattr(func, '_api_doc', None)
        if (api_doc and ('section' in api_doc) and (method in valid_methods)):
            docs = {}
            docs['doc'] = inspect.getdoc(func)
            if ('extends' in api_doc):
                docs.update(api_doc['extends'])
                docs['parameters'] = {}
            docs.update(api_doc)
            if ('parameters' in api_doc):
                docs['parameters'].pop('timeout', None)
            notes = docs.get('notes')
            if notes:
                notes = '\n'.join(notes)
                if docs['doc']:
                    docs['doc'] += ('\n\n' + notes)
                else:
                    docs['doc'] = notes
            uri = (docs.get('uri') or '/'.join((url_prefix, action)))
            docs['uri'] = uri
            if ('supports_rss' not in docs):
                docs['supports_rss'] = False
            if api_doc['uses_site']:
                docs['in-subreddit'] = True
            oauth_perms = getattr(func, 'oauth2_perms', {})
            oauth_allowed = oauth_perms.get('oauth2_allowed', False)
            if (not oauth_allowed):
                docs['oauth_scopes'] = []
            else:
                docs['oauth_scopes'] = (oauth_perms['required_scopes'] or [None])
            if oauth_only:
                if (not oauth_allowed):
                    continue
                for scope in docs['oauth_scopes']:
                    for variant in chain([uri], docs.get('uri_variants', [])):
                        api_docs[scope][variant][method] = docs
            else:
                for variant in chain([uri], docs.get('uri_variants', [])):
                    api_docs[docs['section']][variant][method] = docs
    return api_docs
