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_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