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