def _format_prototype (self, function, is_pointer, title):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_prototype (self, function,
is_pointer, title)
params = function.get_extension_attribute ('gi-extension', 'parameters')
if params is None:
return HtmlFormatter._format_prototype (self, function,
is_pointer, title)
c_name = function._make_name()
if self.__gi_extension.language == 'python':
template = self.engine.get_template('python_prototype.html')
else:
template = self.engine.get_template('javascript_prototype.html')
if type (function) == SignalSymbol:
comment = "%s callback for the '%s' signal" % (self.__gi_extension.language, c_name)
elif type (function) == VFunctionSymbol:
comment = "%s implementation of the '%s' virtual method" % \
(self.__gi_extension.language, c_name)
else:
comment = "%s wrapper for '%s'" % (self.__gi_extension.language,
c_name)
res = template.render ({'return_value': function.return_value,
'function_name': title, 'parameters':
params, 'comment': comment, 'throws': function.throws,
'out_params': [], 'is_method': function.is_method})
return res
def __init__(self, extension, doc_database):
module_path = os.path.dirname(__file__)
searchpath = [os.path.join(module_path, "templates")]
self.__extension = extension
self.__doc_database = doc_database
HtmlFormatter.__init__(self, searchpath)
self.__docstring_formatter = MyRestParser(extension)
self.__current_module_name = None
self.__current_package_name = None
def _format_type_tokens (self, type_tokens):
if self.__gi_extension.language != 'c':
new_tokens = []
for tok in type_tokens:
# FIXME : shouldn't we rather QualifiedSymbol.get_type_link() ?
if tok not in ['*', 'const ', 'restrict ', 'volatile ']:
new_tokens.append (tok)
return HtmlFormatter._format_type_tokens (self, new_tokens)
return HtmlFormatter._format_type_tokens (self, type_tokens)
def _format_constant(self, constant):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_constant (self, constant)
template = self.engine.get_template('constant.html')
out = template.render ({'symbol': constant,
'definition': None,
'constant': constant})
return (out, False)
def _format_struct (self, struct):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_struct (self, struct)
members_list = self._format_members_list (struct.members, 'Attributes')
template = self.engine.get_template ("python_compound.html")
out = template.render ({"compound": struct,
"members_list": members_list})
return (out, False)
def format_symbol(self, symbol, link_resolver):
if isinstance(symbol, Symbol):
if self.__current_module_name != symbol.filename:
self.__current_module_name = symbol.filename
relpath = os.path.relpath(self.__current_module_name,
self.__extension.package_root)
modname = os.path.splitext(relpath)[0].replace('/', '.')
self.__current_package_name = modname
return HtmlFormatter.format_symbol(self, symbol, link_resolver)
def _format_callable_summary (self, callable_, return_value, function_name,
is_callable, is_pointer):
if self.__gi_extension.language in ["python", "javascript"]:
is_pointer = False
return_value = None
elif self.__gi_extension.language in ['c']:
if not return_value:
return_value = 'void'
return HtmlFormatter._format_callable_summary (self, callable_, return_value,
function_name, is_callable, is_pointer)
def _format_linked_symbol (self, symbol):
if self.__gi_extension.language == 'c':
res = HtmlFormatter._format_linked_symbol (self, symbol)
if symbol == None:
res = 'void'
return res
if not isinstance (symbol, QualifiedSymbol):
return HtmlFormatter._format_linked_symbol (self, symbol)
gi_name = symbol.get_extension_attribute ('gi-extension', 'gi_name')
if gi_name is None:
return HtmlFormatter._format_linked_symbol (self, symbol)
fund = self.__gi_extension._fundamentals.get(gi_name)
if fund:
link = Link(fund.ref, fund._title, gi_name)
return self._format_type_tokens ([link])
res = self._format_type_tokens (symbol.type_tokens)
return res
def _format_return_value_symbol (self, retval):
is_void = retval[0] is None or \
retval[0].get_extension_attribute('gi-extension',
'gi_name') == 'none'
if self.__gi_extension.language == 'c':
if is_void:
retval = [None]
else:
retval = retval[:1]
elif is_void:
retval = retval[1:] or [None]
return HtmlFormatter._format_return_value_symbol (self, retval)
def _format_parameter_symbol (self, parameter):
if self.__gi_extension.language != 'c':
direction = parameter.get_extension_attribute ('gi-extension',
'direction')
if direction == 'out':
return (None, False)
gi_name = parameter.get_extension_attribute ('gi-extension', 'gi_name')
parameter.extension_contents['type-link'] = self._format_linked_symbol (parameter)
else:
parameter.extension_contents.pop('type-link', None)
res = HtmlFormatter._format_parameter_symbol (self, parameter)
return res
def __init__(self, doc_repo):
"""Constructor for `BaseExtension`.
This should never get called directly.
Args:
doc_repo: The `doc_repo.DocRepo` instance which documentation
is being generated.
"""
self.doc_repo = doc_repo
DocTree.resolve_placeholder_signal.connect(
self.__resolve_placeholder_cb)
DocTree.update_signal.connect(self.__update_doc_tree_cb)
if not hasattr(self, 'formatters'):
self.formatters = {"html": HtmlFormatter([])}
self.__created_symbols = defaultdict(OrderedSet)
self.__package_root = None
def _format_class_symbol(self, klass):
constructor = self.__doc_database.get_session().query(FunctionSymbol).filter(
FunctionSymbol.is_ctor_for==klass.unique_name).first()
if constructor is None:
return HtmlFormatter._format_class_symbol(self, klass)
hierarchy = self._format_hierarchy(klass)
template = self.engine.get_template('python_class.html')
link_resolver = self.__extension.doc_repo.link_resolver
self.format_symbol(constructor, link_resolver)
constructor.link.title = klass.display_name
constructor = self._format_callable(constructor, 'class',
klass.link.title)[0]
return (template.render({'symbol': klass,
'klass': klass,
'constructor': constructor,
'hierarchy': hierarchy}),
False)
def _format_property_summary (self, prop):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_property_summary (self, prop)
template = self.engine.get_template('property_summary.html')
property_type = None
prop_link = self._format_linked_symbol (prop)
tags = {}
if prop.comment:
tags = prop.comment.tags
return template.render({
'symbol': prop,
'tags': tags,
'property_type': property_type,
'property_link': prop_link,
'extra_contents': prop.extension_contents,
})
def _format_class_symbol(self, klass):
constructor = self.__doc_database.get_session().query(FunctionSymbol).filter(
FunctionSymbol.is_ctor_for==klass.unique_name).first()
if constructor is None:
return HtmlFormatter._format_class_symbol(self, klass)
hierarchy = self._format_hierarchy(klass)
template = self.engine.get_template('python_class.html')
self._format_symbols(constructor.get_children_symbols())
constructor.formatted_doc = self.format_comment(constructor.comment)
constructor.link.title = klass.display_name
constructor = self._format_callable(constructor, 'class',
klass.link.title)[0]
return (template.render({'symbol': klass,
"editing_link":
self._format_editing_link(klass),
'klass': klass,
'constructor': constructor,
'hierarchy': hierarchy}),
False)
def _format_alias_summary (self, alias):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_alias_summary (self, alias)
return self._format_compound_summary (alias)
def _format_constant_summary (self, constant):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_constant_summary (self, constant)
return self._format_compound_summary (constant)
def _format_parameter_symbol (self, parameter):
if parameter.type_tokens:
parameter.extension_contents['type-link'] = \
self._format_type_tokens(parameter.type_tokens)
return HtmlFormatter._format_parameter_symbol(self, parameter)
def __init__(self):
HtmlFormatter.__init__(self, [])
self._docstring_formatter = GtkDocStringFormatter()
def __init__(self, gi_extension, link_resolver):
module_path = os.path.dirname(__file__)
searchpath = [os.path.join(module_path, "templates")]
self.__gi_extension = gi_extension
self.__link_resolver = link_resolver
HtmlFormatter.__init__(self, searchpath)
def _format_enum_summary (self, enum):
if self.__gi_extension.language == 'c':
return HtmlFormatter._format_enum_summary (self, enum)
return self._format_compound_summary (enum)
