def generate_sphinx(operation_name):
"""Make a sphinx-style docstring.
This is used to generate the off-line docs.
"""
op = Operation.new_from_name(operation_name)
if (op.get_flags() & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
# we are only interested in non-deprecated args
args = [[name, flags] for name, flags in op.get_args()
if not flags & _DEPRECATED]
# find the first required input image arg, if any ... that will be self
member_x = None
for name, flags in args:
if ((flags & _INPUT) != 0 and (flags & _REQUIRED) != 0
and op.get_typeof(name) == GValue.image_type):
member_x = name
break
required_input = [
name for name, flags in args if (flags & _INPUT) != 0 and
(flags & _REQUIRED) != 0 and name != member_x
]
optional_input = [
name for name, flags in args
if (flags & _INPUT) != 0 and (flags & _REQUIRED) == 0
]
required_output = [
name for name, flags in args
if ((flags & _OUTPUT) != 0 and (flags & _REQUIRED) != 0) or (
(flags & _INPUT) != 0 and (flags & _REQUIRED) != 0 and
(flags & _MODIFY) != 0)
]
optional_output = [
name for name, flags in args
if (flags & _OUTPUT) != 0 and (flags & _REQUIRED) == 0
]
if member_x is not None:
result = '.. method:: '
else:
result = '.. staticmethod:: '
args = []
args += required_input
args += [
x + ' = ' + GValue.gtype_to_python(op.get_typeof(x))
for x in optional_input
]
args += [x + ' = bool' for x in optional_output]
result += operation_name + '(' + ", ".join(args) + ')\n\n'
description = op.get_description()
result += description[0].upper() + description[1:] + '.\n\n'
result += 'Example:\n'
result += ' ' + ', '.join(required_output) + ' = '
if member_x is not None:
result += member_x + "." + operation_name + '('
else:
result += 'pyvips.Image.' + operation_name + '('
result += ', '.join(required_input)
if len(optional_input) > 0 and len(required_input) > 0:
result += ', '
result += ', '.join([
x + ' = ' + GValue.gtype_to_python(op.get_typeof(x))
for x in optional_input
])
result += ')\n\n'
for name in required_input + optional_input:
result += (':param {0} {1}: {2}\n'.format(
GValue.gtype_to_python(op.get_typeof(name)), name,
op.get_blurb(name)))
for name in optional_output:
result += (':param bool {0}: enable output: {1}\n'.format(
name, op.get_blurb(name)))
output_types = [
GValue.gtype_to_python(op.get_typeof(name))
for name in required_output
]
if len(output_types) == 1:
output_type = output_types[0]
else:
output_type = 'list[' + ', '.join(output_types) + ']'
if len(optional_output) > 0:
output_types += ['Dict[str, mixed]']
output_type += ' or list[' + ', '.join(output_types) + ']'
result += ':rtype: ' + output_type + '\n'
result += ':raises Error:\n'
return result
def argstr(name):
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(op.get_typeof(name)),
op.get_blurb(name)))
def generate_docstring(operation_name):
"""Make a google-style docstring.
This is used to generate help() output.
"""
if operation_name in Operation._docstring_cache:
return Operation._docstring_cache[operation_name]
op = Operation.new_from_name(operation_name)
if (op.get_flags() & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
# we are only interested in non-deprecated args
args = [[name, flags] for name, flags in op.get_args()
if not flags & _DEPRECATED]
# find the first required input image arg, if any ... that will be self
member_x = None
for name, flags in args:
if ((flags & _INPUT) != 0 and (flags & _REQUIRED) != 0
and op.get_typeof(name) == GValue.image_type):
member_x = name
break
required_input = [
name for name, flags in args if (flags & _INPUT) != 0 and
(flags & _REQUIRED) != 0 and name != member_x
]
optional_input = [
name for name, flags in args
if (flags & _INPUT) != 0 and (flags & _REQUIRED) == 0
]
required_output = [
name for name, flags in args
if ((flags & _OUTPUT) != 0 and (flags & _REQUIRED) != 0) or (
(flags & _INPUT) != 0 and (flags & _REQUIRED) != 0 and
(flags & _MODIFY) != 0)
]
optional_output = [
name for name, flags in args
if (flags & _OUTPUT) != 0 and (flags & _REQUIRED) == 0
]
description = op.get_description()
result = description[0].upper() + description[1:] + ".\n\n"
result += "Example:\n"
result += " " + ", ".join(required_output) + " = "
if member_x is not None:
result += member_x + "." + operation_name + "("
else:
result += "pyvips.Image." + operation_name + "("
result += ", ".join(required_input)
if len(optional_input) > 0 and len(required_input) > 0:
result += ", "
result += ", ".join([
x + " = " + GValue.gtype_to_python(op.get_typeof(x))
for x in optional_input
])
result += ")\n"
def argstr(name):
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(op.get_typeof(name)),
op.get_blurb(name)))
result += "\nReturns:\n"
for name in required_output:
result += argstr(name)
names = []
if member_x is not None:
names += [member_x]
names += required_input
result += "\nArgs:\n"
for name in names:
result += argstr(name)
if len(optional_input) > 0:
result += "\nKeyword args:\n"
for name in optional_input:
result += argstr(name)
if len(optional_output) > 0:
result += "\nOther Parameters:\n"
for name in optional_output:
result += argstr(name)
result += "\nRaises:\n :class:`.Error`\n"
# add to cache to save building again
Operation._docstring_cache[operation_name] = result
return result
def generate_sphinx(operation_name):
"""Make a sphinx-style docstring.
This is used to generate the off-line docs.
"""
intro = Introspect.get(operation_name)
if (intro.flags & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
if intro.member_x is not None:
result = '.. method:: '
else:
result = '.. staticmethod:: '
args = []
args += intro.method_args
args += [
x + '=' + GValue.gtype_to_python(intro.details[x]['type'])
for x in intro.optional_input
]
args += [x + '=bool' for x in intro.optional_output]
result += operation_name + '(' + ", ".join(args) + ')\n\n'
result += intro.description[0].upper() + \
intro.description[1:] + '.\n\n'
result += 'Example:\n'
result += ' ' + ', '.join(intro.required_output) + ' = '
if intro.member_x is not None:
result += intro.member_x + "." + operation_name + '('
else:
result += 'pyvips.Image.' + operation_name + '('
args = []
args += intro.method_args
args += [
x + '=' + GValue.gtype_to_python(intro.details[x]['type'])
for x in intro.optional_input
]
result += ', '.join(args)
result += ')\n\n'
for name in intro.method_args + intro.optional_input:
details = intro.details[name]
result += (':param {0}: {1}\n'.format(name, details['blurb']))
result += (':type {0}: {1}\n'.format(
name, GValue.gtype_to_python(details['type'])))
for name in intro.optional_output:
result += (':param {0}: enable output: {1}\n'.format(
name, intro.details[name]['blurb']))
result += (':type {0}: bool\n'.format(name))
output_types = [
GValue.gtype_to_python(intro.details[name]['type'])
for name in intro.required_output
]
if len(output_types) == 1:
output_type = output_types[0]
else:
output_type = 'list[' + ', '.join(output_types) + ']'
if len(intro.optional_output) > 0:
output_types += ['Dict[str, mixed]']
output_type += ' or list[' + ', '.join(output_types) + ']'
result += ':rtype: ' + output_type + '\n'
result += ':raises Error:\n'
return result
def argstr(name):
details = intro.details[name]
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(details['type']),
details['blurb']))
def generate_docstring(operation_name):
"""Make a google-style docstring.
This is used to generate help() output.
"""
# we cache these to save regeneration
if operation_name in Operation._docstring_cache:
return Operation._docstring_cache[operation_name]
intro = Introspect.get(operation_name)
if (intro.flags & _OPERATION_DEPRECATED) != 0:
raise Error('No such operator.',
'operator "{0}" is deprecated'.format(operation_name))
result = intro.description[0].upper() + intro.description[1:] + '.\n\n'
result += 'Example:\n'
result += ' ' + ', '.join(intro.required_output) + ' = '
if intro.member_x is not None:
result += intro.member_x + '.' + operation_name + '('
else:
result += 'pyvips.Image.' + operation_name + '('
args = []
args += intro.method_args
args += [
x + '=' + GValue.gtype_to_python(intro.details[x]['type'])
for x in intro.optional_input
]
args += [x + '=bool' for x in intro.optional_output]
result += ", ".join(args) + ')\n'
def argstr(name):
details = intro.details[name]
return (u' {0} ({1}): {2}\n'.format(
name, GValue.gtype_to_python(details['type']),
details['blurb']))
result += '\nReturns:\n'
for name in intro.required_output:
result += argstr(name)
result += '\nArgs:\n'
if intro.member_x is not None:
result += argstr(intro.member_x)
for name in intro.method_args:
result += argstr(name)
if len(intro.optional_input) > 0:
result += '\nKeyword args:\n'
for name in intro.optional_input:
result += argstr(name)
if len(intro.optional_output) > 0:
result += '\nOther Parameters:\n'
for name in intro.optional_output:
result += argstr(name)
result += '\nRaises:\n :class:`.Error`\n'
# add to cache to save building again
Operation._docstring_cache[operation_name] = result
return result
