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
