def format_header_from_file(style, source_code_info, proto_name, v2_link): """Format RST header based on special file level title Args: style: underline style, e.g. '=', '-'. source_code_info: SourceCodeInfo object. proto_name: If the file_level_comment does not contain a user specified title, use this as page title. Returns: RST formatted header, and file level comment without page title strings. """ anchor = format_anchor(file_cross_ref_label(proto_name)) stripped_comment = annotations.without_annotations( strip_leading_space('\n'.join( c + '\n' for c in source_code_info.file_level_comments))) formatted_extension = '' if annotations.EXTENSION_ANNOTATION in source_code_info.file_level_annotations: extension = source_code_info.file_level_annotations[ annotations.EXTENSION_ANNOTATION] formatted_extension = format_extension(extension) if annotations.DOC_TITLE_ANNOTATION in source_code_info.file_level_annotations: return anchor + format_header( style, source_code_info.file_level_annotations[ annotations.DOC_TITLE_ANNOTATION] ) + v2_link + "\n\n" + formatted_extension, stripped_comment return anchor + format_header( style, proto_name) + v2_link + "\n\n" + formatted_extension, stripped_comment
def format_comment_with_annotations(comment, type_name=''): """Format a comment string with additional RST for annotations. Args: comment: comment string. type_name: optional, 'message' or 'enum' may be specified for additional message/enum specific annotations. Returns: A string with additional RST from annotations. """ alpha_warning = '' if annotations.ALPHA_ANNOTATION in comment.annotations: experimental_warning = ( '.. warning::\n This API is alpha and is not covered by the :ref:`threat model <arch_overview_threat_model>`.\n\n' ) formatted_extension = '' if annotations.EXTENSION_ANNOTATION in comment.annotations: extension = comment.annotations[annotations.EXTENSION_ANNOTATION] formatted_extension = format_extension(extension) formatted_extension_category = '' if annotations.EXTENSION_CATEGORY_ANNOTATION in comment.annotations: for category in comment.annotations[ annotations.EXTENSION_CATEGORY_ANNOTATION].split(","): formatted_extension_category += format_extension_category(category) comment = annotations.without_annotations( strip_leading_space(comment.raw) + '\n') return alpha_warning + comment + formatted_extension + formatted_extension_category
def format_comment_with_annotations(comment, show_wip_warning=False): """Format a comment string with additional RST for annotations. Args: comment: comment string. show_wip_warning: whether to show the work in progress warning. Returns: A string with additional RST from annotations. """ wip_warning = '' if show_wip_warning: wip_warning = WIP_WARNING formatted_extension = '' if annotations.EXTENSION_ANNOTATION in comment.annotations: extension = comment.annotations[annotations.EXTENSION_ANNOTATION] formatted_extension = format_extension(extension) formatted_extension_category = '' if annotations.EXTENSION_CATEGORY_ANNOTATION in comment.annotations: for category in comment.annotations[ annotations.EXTENSION_CATEGORY_ANNOTATION].split(","): formatted_extension_category += format_extension_category(category) comment = annotations.without_annotations( strip_leading_space(comment.raw) + '\n') return comment + wip_warning + formatted_extension + formatted_extension_category
def _comment(self, comment, show_wip_warning=False): """Format a comment string with additional RST for annotations. """ return self.tpl_comment.render( comment=annotations.without_annotations(comment.raw), wip_warning=WIP_WARNING if show_wip_warning else "", extension=( self._extension(extension) if (extension := comment.annotations.get(annotations.EXTENSION_ANNOTATION)) else ""), categories=self._extension_categories(comment))
def _header_from_file(self, source_code_info, file_proto, has_messages) -> str: """Format RST header based on special file level title """ proto_name = file_proto.name stripped_comment = annotations.without_annotations( '\n'.join(c + '\n' for c in source_code_info.file_level_comments)) formatted_extension = ( self._extension( source_code_info.file_level_annotations[annotations.EXTENSION_ANNOTATION]) if annotations.EXTENSION_ANNOTATION in source_code_info.file_level_annotations else "") title = ( source_code_info.file_level_annotations[annotations.DOC_TITLE_ANNOTATION] if annotations.DOC_TITLE_ANNOTATION in source_code_info.file_level_annotations else proto_name) return self.tpl_header.render( anchor=file_cross_ref_label(proto_name), title=f"{title} (proto)", style="=", orphan=not has_messages, extension=formatted_extension, comment=stripped_comment, warnings=self._warnings(file_proto))
def format_comment_with_annotations(comment, type_name=''): """Format a comment string with additional RST for annotations. Args: comment: comment string. type_name: optional, 'message' or 'enum' may be specified for additional message/enum specific annotations. Returns: A string with additional RST from annotations. """ formatted_extension = '' if annotations.EXTENSION_ANNOTATION in comment.annotations: extension = comment.annotations[annotations.EXTENSION_ANNOTATION] formatted_extension = format_extension(extension) formatted_extension_category = '' if annotations.EXTENSION_CATEGORY_ANNOTATION in comment.annotations: for category in comment.annotations[ annotations.EXTENSION_CATEGORY_ANNOTATION].split(","): formatted_extension_category += format_extension_category(category) comment = annotations.without_annotations( strip_leading_space(comment.raw) + '\n') return comment + formatted_extension + formatted_extension_category