def to_ast(self, text, link_resolver):
"""
Given a gtk-doc comment string, returns an opaque PyCapsule
containing the document root.
This is an optimization allowing to parse the docstring only
once, and to render it multiple times with
`ast_to_html`, links discovery and
most of the link resolution being lazily done in that second phase.
If you don't care about performance, you should simply
use `translate`.
Args:
text: unicode, the docstring to parse.
link_resolver: hotdoc.core.links.LinkResolver, an object
which will be called to retrieve `hotdoc.core.links.Link`
objects.
Returns:
capsule: A PyCapsule wrapping an opaque C pointer, which
can be passed to `ast_to_html`
afterwards.
"""
if GtkDocStringFormatter.escape_html:
text = cgi.escape(text)
return cmark.gtkdoc_to_ast(text, link_resolver)
def format(self, formatter, link_resolver, output):
"""
Banana banana
"""
if self.ast:
self.formatted_contents =\
cmark.ast_to_html(self.ast, link_resolver)
elif self.comment:
if self.comment.short_description:
ast = cmark.gtkdoc_to_ast(self.comment.short_description,
link_resolver)
self.short_description =\
cmark.ast_to_html(ast, link_resolver).strip()
if self.short_description.startswith('<p>'):
self.short_description = self.short_description[3:-4]
if self.comment.title:
ast = cmark.gtkdoc_to_ast(self.comment.title,
link_resolver)
self.title =\
cmark.ast_to_html(ast, link_resolver).strip()
if self.title.startswith('<p>'):
self.title = self.title[3:-4]
description = u'# %s\n\n%s\n' % (self.comment.title,
self.comment.description)
else:
description = self.comment.description
self.title = self.source_file
ast = cmark.gtkdoc_to_ast(description, link_resolver)
self.formatted_contents =\
cmark.ast_to_html(ast, link_resolver)
if not self.title and self.source_file:
self.title = os.path.splitext(self.source_file)[0]
self.output_attrs = defaultdict(lambda: defaultdict(dict))
formatter.prepare_page_attributes(self)
Page.formatting_signal(self, formatter)
self.__format_symbols(formatter, link_resolver)
self.detailed_description =\
formatter.format_page(self)[0]
if output:
formatter.write_page(self, output)
def test_wrong_multiline_link(self):
inp = (u'a #wrong_link\n\n'
'and #another_wrong_link\n'
'and then #yet_another_wrong_link')
_, diagnostics = cmark.gtkdoc_to_ast(inp, self.link_resolver)
self.assertEqual(len(diagnostics), 3)
diag = diagnostics[0]
self.assertEqual(diag.lineno, 0)
self.assertEqual(diag.column, 2)
diag = diagnostics[1]
self.assertEqual(diag.lineno, 2)
self.assertEqual(diag.column, 4)
diag = diagnostics[2]
self.assertEqual(diag.lineno, 3)
self.assertEqual(diag.column, 9)
def test_wrong_multiline_link(self):
inp = (u'a #wrong_link\n\n'
'and #another_wrong_link\n'
'and then #yet_another_wrong_link')
_, diagnostics = cmark.gtkdoc_to_ast(inp, self.link_resolver)
self.assertEqual(len(diagnostics), 3)
diag = diagnostics[0]
self.assertEqual(diag.lineno, 0)
self.assertEqual(diag.column, 2)
diag = diagnostics[1]
self.assertEqual(diag.lineno, 2)
self.assertEqual(diag.column, 4)
diag = diagnostics[2]
self.assertEqual(diag.lineno, 3)
self.assertEqual(diag.column, 9)
def test_input_none(self):
inp = None
with self.assertRaises(TypeError):
ast, _ = cmark.gtkdoc_to_ast(inp, self.link_resolver)
self.assertEqual(ast, None)
def assertOutputs(self, inp, expected):
ast, _ = cmark.gtkdoc_to_ast(inp, self.link_resolver)
out = cmark.ast_to_html(ast, self.link_resolver)[0]
self.assertEqual(out, expected)
def comment_to_ast(self, comment, link_resolver):
"""
Given a gtk-doc comment string, returns an opaque PyCapsule
containing the document root.
This is an optimization allowing to parse the docstring only
once, and to render it multiple times with
`ast_to_html`, links discovery and
most of the link resolution being lazily done in that second phase.
If you don't care about performance, you should simply
use `translate`.
Args:
text: unicode, the docstring to parse.
link_resolver: hotdoc.core.links.LinkResolver, an object
which will be called to retrieve `hotdoc.core.links.Link`
objects.
Returns:
capsule: A PyCapsule wrapping an opaque C pointer, which
can be passed to `ast_to_html`
afterwards.
diagnostics: A list of diagnostics as output by the gtk-doc cmark
extension
"""
assert comment is not None
text = comment.description
if (GtkDocStringFormatter.remove_xml_tags or comment.filename in
GtkDocStringFormatter.gdbus_codegen_sources):
text = re.sub('<.*?>', '', text)
if GtkDocStringFormatter.escape_html:
text = cgi.escape(text)
ast, diagnostics = cmark.gtkdoc_to_ast(text, link_resolver)
for diag in diagnostics:
if (comment.filename and comment.filename not in
GtkDocStringFormatter.gdbus_codegen_sources):
column = diag.column + comment.col_offset
if diag.lineno == 0:
column += comment.initial_col_offset
lines = text.split('\n')
line = lines[diag.lineno]
i = 0
while line[i] == ' ':
i += 1
column += i - 1
if diag.lineno > 0 and any([c != ' ' for c in
lines[diag.lineno - 1]]):
column += 1
lineno = -1
if comment.lineno != -1:
lineno = (comment.lineno - 1 + comment.line_offset +
diag.lineno)
warn(
diag.code,
message=diag.message,
filename=comment.filename,
lineno=lineno,
column=column)
return ast
def assertOutputs(self, inp, expected):
ast, diagnostics = cmark.gtkdoc_to_ast(inp, self.link_resolver, None,
None)
out = cmark.ast_to_html(ast, self.link_resolver)[0]
self.assertEqual(out, expected)
return ast, diagnostics
def test_input_none(self):
inp = None
with self.assertRaises(TypeError):
ast, _ = cmark.gtkdoc_to_ast(inp, self.link_resolver)
self.assertEqual(ast, None)
def assertOutputs(self, inp, expected):
ast, _ = cmark.gtkdoc_to_ast(inp, self.link_resolver)
out = cmark.ast_to_html(ast, self.link_resolver)[0]
self.assertEqual(out, expected)
