def documentation(self, add_to=None):
"""Produces general documentation for the interface"""
doc = OrderedDict if add_to is None else add_to
usage = self.interface.spec.__doc__
if usage:
doc['usage'] = usage
if getattr(self, 'requires', None):
doc['requires'] = [getattr(requirement, '__doc__', requirement.__name__) for requirement in self.requires]
doc['outputs'] = OrderedDict()
doc['outputs']['format'] = self.outputs.__doc__
doc['outputs']['content_type'] = self.outputs.content_type
parameters = [param for param in self.parameters if not param in ('request', 'response', 'self')
and not param in ('api_version', 'body')
and not param.startswith('hug_')
and not hasattr(param, 'directive')]
if parameters:
inputs = doc.setdefault('inputs', OrderedDict())
types = self.interface.spec.__annotations__
for argument in parameters:
kind = types.get(argument, text)
if getattr(kind, 'directive', None) is True:
continue
input_definition = inputs.setdefault(argument, OrderedDict())
input_definition['type'] = kind if isinstance(kind, str) else kind.__doc__
default = self.defaults.get(argument, None)
if default is not None:
input_definition['default'] = default
return doc
def generate(module, base_url="", api_version=None):
'''Generates documentation based on a Hug API module, base_url, and api_version (if applicable)'''
documentation = OrderedDict()
overview = module.__doc__
if overview:
documentation['overview'] = overview
documentation['versions'] = OrderedDict()
versions = module.__hug__.versions
for version in (api_version, ) if api_version else versions:
documentation['versions'][version] = OrderedDict()
for url, methods in module.__hug__.routes.items():
for method, versions in methods.items():
for version, handler in versions.items():
if version == None:
applies_to = versions
else:
applies_to = (version, )
for version in applies_to:
if api_version and version != api_version:
continue
doc = documentation['versions'][version].setdefault(url, OrderedDict())
doc = doc.setdefault(method, OrderedDict())
usage = handler.api_function.__doc__
if usage:
doc['usage'] = usage
for example in handler.examples:
example_text = "{0}{1}{2}".format(base_url, '/v{0}'.format(version) if version else '', url)
if isinstance(example, str):
example_text += "?{0}".format(example)
doc_examples = doc.setdefault('examples', [])
if not example_text in doc_examples:
doc_examples.append(example_text)
doc['outputs'] = OrderedDict(format=handler.output_format.__doc__,
content_type=handler.content_type)
parameters = [param for param in handler.accepted_parameters if not param in ('request',
'response')
and not param.startswith('hug_')]
if parameters:
inputs = doc.setdefault('inputs', OrderedDict())
types = handler.api_function.__annotations__
for argument in parameters:
input_definition = inputs.setdefault(argument, OrderedDict())
input_definition['type'] = types.get(argument, hug.types.text).__doc__
default = handler.defaults.get(argument, None)
if default is not None:
input_definition['default'] = default
if len(documentation['versions']) == 1:
documentation.update(tuple(documentation['versions'].values())[0])
documentation.pop('versions')
else:
documentation['versions'].pop(None, '')
return documentation
def documentation(self, add_to=None):
"""Produces general documentation for the interface"""
doc = OrderedDict if add_to is None else add_to
usage = self.interface.spec.__doc__
if usage:
doc['usage'] = usage
if getattr(self, 'requires', None):
doc['requires'] = [
getattr(requirement, '__doc__', requirement.__name__)
for requirement in self.requires
]
doc['outputs'] = OrderedDict()
doc['outputs']['format'] = self.outputs.__doc__
doc['outputs']['content_type'] = self.outputs.content_type
parameters = [
param for param in self.parameters
if not param in ('request', 'response', 'self') and not param in
('api_version', 'body') and not param.startswith('hug_')
and not hasattr(param, 'directive')
]
if parameters:
inputs = doc.setdefault('inputs', OrderedDict())
types = self.interface.spec.__annotations__
for argument in parameters:
kind = types.get(argument, text)
if getattr(kind, 'directive', None) is True:
continue
input_definition = inputs.setdefault(argument, OrderedDict())
input_definition['type'] = kind if isinstance(
kind, str) else kind.__doc__
default = self.defaults.get(argument, None)
if default is not None:
input_definition['default'] = default
return doc
def documentation(self, add_to=None):
"""Produces general documentation for the interface"""
doc = OrderedDict if add_to is None else add_to
usage = self.interface.spec.__doc__
if usage:
doc["usage"] = usage
if getattr(self, "requires", None):
doc["requires"] = [
getattr(requirement, "__doc__", requirement.__name__)
for requirement in self.requires
]
doc["outputs"] = OrderedDict()
doc["outputs"]["format"] = self.outputs.__doc__
doc["outputs"]["content_type"] = self.outputs.content_type
parameters = [
param for param in self.parameters
if not param in ("request", "response", "self") and not param in
("api_version", "body") and not param.startswith("hug_")
and not hasattr(param, "directive")
]
if parameters:
inputs = doc.setdefault("inputs", OrderedDict())
types = self.interface.spec.__annotations__
for argument in parameters:
kind = types.get(self._remap_entry(argument), text)
if getattr(kind, "directive", None) is True:
continue
input_definition = inputs.setdefault(argument, OrderedDict())
input_definition["type"] = kind if isinstance(
kind, str) else kind.__doc__
default = self.defaults.get(argument, None)
if default is not None:
input_definition["default"] = default
return doc
def generate(module, base_url="", api_version=None):
'''Generates documentation based on a Hug API module, base_url, and api_version (if applicable)'''
documentation = OrderedDict()
overview = module.__doc__
if overview:
documentation['overview'] = overview
documentation['versions'] = OrderedDict()
versions = module.__hug__.versions
for version in (api_version, ) if api_version else versions:
documentation['versions'][version] = OrderedDict()
for url, methods in module.__hug__.routes.items():
for method, versions in methods.items():
for version, handler in versions.items():
if version == None:
applies_to = versions
else:
applies_to = (version, )
for version in applies_to:
if api_version and version != api_version:
continue
doc = documentation['versions'][version].setdefault(
url, OrderedDict())
doc = doc.setdefault(method, OrderedDict())
usage = handler.api_function.__doc__
if usage:
doc['usage'] = usage
for example in handler.examples:
example_text = "{0}{1}{2}".format(
base_url,
'/v{0}'.format(version) if version else '', url)
if isinstance(example, str):
example_text += "?{0}".format(example)
doc_examples = doc.setdefault('examples', [])
if not example_text in doc_examples:
doc_examples.append(example_text)
doc['outputs'] = OrderedDict(
format=handler.output_format.__doc__,
content_type=handler.content_type)
parameters = [
param for param in handler.accepted_parameters
if not param in ('request', 'response')
and not param.startswith('hug_')
]
if parameters:
inputs = doc.setdefault('inputs', OrderedDict())
types = handler.api_function.__annotations__
for argument in parameters:
input_definition = inputs.setdefault(
argument, OrderedDict())
input_definition['type'] = types.get(
argument, hug.types.text).__doc__
default = handler.defaults.get(argument, None)
if default is not None:
input_definition['default'] = default
if len(documentation['versions']) == 1:
documentation.update(tuple(documentation['versions'].values())[0])
documentation.pop('versions')
else:
documentation['versions'].pop(None, '')
return documentation
