def _build_function_page(page_info):
"""Given a FunctionPageInfo object Return the page as an md string."""
parts = [f'# {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
if page_info.signature is not None:
parts.append(_build_signature(page_info))
parts.append('\n\n')
# This will be replaced by the "Used in: <notebooks>" whenever it is run.
parts.append('<!-- Placeholder for "Used in" -->\n')
parts.extend(str(item) for item in page_info.doc.docstring_parts)
parts.append(_build_compatibility(page_info.doc.compatibility))
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
return ''.join(parts)
def _build_function_page(page_info: parser.FunctionPageInfo,
table_view: bool) -> str:
"""Constructs a markdown page given a `FunctionPageInfo` object.
Args:
page_info: A `FunctionPageInfo` object containing information that's used to
create a function page.
For example, see https://www.tensorflow.org/api_docs/python/tf/concat
table_view: If True, `Args`, `Returns`, `Raises` or `Attributes` will be
converted to a tabular format while generating markdown. If False, they
will be converted to a markdown List view.
Returns:
The function markdown page.
"""
parts = [f'# {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
if page_info.signature is not None:
parts.append(_build_signature(page_info, obj_name=page_info.full_name))
parts.append('\n\n')
# This will be replaced by the "Used in: <notebooks>" whenever it is run.
parts.append('<!-- Placeholder for "Used in" -->\n')
for item in page_info.doc.docstring_parts:
parts.append(
_format_docstring(
item,
table_view,
table_title_template='<h2 class="add-link">{title}</h2>'))
parts.append(_build_compatibility(page_info.doc.compatibility))
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
def _build_function_page(page_info: parser.FunctionPageInfo) -> str:
"""Constructs a markdown page given a `FunctionPageInfo` object.
Args:
page_info: A `FunctionPageInfo` object containing information that's used to
create a function page.
For example, see https://www.tensorflow.org/api_docs/python/tf/concat
Returns:
The function markdown page.
"""
parts = [f'# {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
if page_info.signature is not None:
parts.append(_build_signature(page_info, obj_name=page_info.full_name))
parts.append('\n\n')
# This will be replaced by the "Used in: <notebooks>" whenever it is run.
parts.append('<!-- Placeholder for "Used in" -->\n')
parts.extend(str(item) for item in page_info.doc.docstring_parts)
parts.append(_build_compatibility(page_info.doc.compatibility))
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
return ''.join(parts)
def _build_module_page(page_info: parser.ModulePageInfo) -> str:
"""Constructs a markdown page given a `ModulePageInfo` object.
Args:
page_info: A `ModulePageInfo` object containing information that's used to
create a module page.
For example, see https://www.tensorflow.org/api_docs/python/tf/data
Returns:
The module markdown page.
"""
parts = [f'# Module: {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
# First line of the docstring i.e. a brief introduction about the symbol.
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
# All lines in the docstring, expect the brief introduction.
parts.extend(str(item) for item in page_info.doc.docstring_parts)
parts.append(_build_compatibility(page_info.doc.compatibility))
parts.append('\n\n')
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
if page_info.modules:
parts.append('## Modules\n\n')
template = '[`{short_name}`]({url}) module'
for item in page_info.modules:
parts.append(template.format(**item._asdict()))
if item.doc.brief:
parts.append(': ' + item.doc.brief)
parts.append('\n\n')
if page_info.classes:
parts.append('## Classes\n\n')
template = '[`class {short_name}`]({url})'
for item in page_info.classes:
parts.append(template.format(**item._asdict()))
if item.doc.brief:
parts.append(': ' + item.doc.brief)
parts.append('\n\n')
if page_info.functions:
parts.append('## Functions\n\n')
template = '[`{short_name}(...)`]({url})'
for item in page_info.functions:
parts.append(template.format(**item._asdict()))
if item.doc.brief:
parts.append(': ' + item.doc.brief)
parts.append('\n\n')
if page_info.other_members:
# TODO(markdaoust): Document the value of the members,
# at least for basic types.
parts.append('## Other Members\n\n')
parts.append(_other_members(page_info.other_members))
return ''.join(parts)
def _build_class_page(page_info: parser.ClassPageInfo) -> str:
"""Constructs a markdown page given a `ClassPageInfo` object.
Args:
page_info: A `ClassPageInfo` object containing information that's used to
create a class page. For example, see
https://www.tensorflow.org/api_docs/python/tf/data/Dataset
Returns:
The class markdown page.
"""
# Add the full_name of the symbol to the page.
parts = ['# {page_info.full_name}\n\n'.format(page_info=page_info)]
# This is used as a marker to initiate the diffing process later down in the
# pipeline.
parts.append('<!-- Insert buttons and diff -->\n')
# Add the github button.
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
# Add the one line docstring of the class.
parts.append(page_info.doc.brief + '\n\n')
# If a class is a child class, add which classes it inherits from.
if page_info.bases:
parts.append('Inherits From: ')
link_template = '[`{short_name}`]({url})'
parts.append(', '.join(
link_template.format(**base._asdict()) for base in page_info.bases))
parts.append('\n\n')
# Build the aliases section and keep it collapses by default.
parts.append(_build_collapsable_aliases(page_info.aliases))
# Split the methods into constructor and other methods.
methods = _split_methods(page_info.methods)
# If the class has a constructor, build its signature.
# The signature will contain the class name followed by the arguments it
# takes.
if methods.constructor is not None:
parts.append(
_build_signature(methods.constructor, obj_name=page_info.full_name))
parts.append('\n\n')
# This will be replaced by the "Used in: <notebooks>" later in the pipeline.
parts.append('<!-- Placeholder for "Used in" -->\n')
# Merge the class and constructor docstring.
parts.extend(
_merge_class_and_constructor_docstring(page_info, methods.constructor))
# Add the compatibility section to the page.
parts.append(_build_compatibility(page_info.doc.compatibility))
parts.append('\n\n')
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
if page_info.attr_block is not None:
parts.append('## Attributes\n')
parts.append(str(page_info.attr_block))
parts.append('\n\n')
# If the class has child classes, add that information to the page.
if page_info.classes:
parts.append('## Child Classes\n')
link_template = ('[`class {class_info.short_name}`]'
'({class_info.url})\n\n')
class_links = sorted(
link_template.format(class_info=class_info)
for class_info in page_info.classes)
parts.extend(class_links)
# If the class contains methods other than the constructor, then add them
# to the page.
if methods.info_dict:
parts.append('## Methods\n\n')
for _, method_info in sorted(methods.info_dict.items()):
parts.append(_build_method_section(method_info))
parts.append('\n\n')
# Add class variables/members if they exist to the page.
if page_info.other_members:
parts.append('## Class Variables\n\n')
parts.append(_other_members(page_info.other_members))
return ''.join(parts)
def _build_module_page(page_info: parser.ModulePageInfo) -> str:
"""Constructs a markdown page given a `ModulePageInfo` object.
Args:
page_info: A `ModulePageInfo` object containing information that's used to
create a module page.
For example, see https://www.tensorflow.org/api_docs/python/tf/data
Returns:
The module markdown page.
"""
parts = [f'# Module: {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
# First line of the docstring i.e. a brief introduction about the symbol.
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
parts.append(_top_compat(page_info, h_level=2))
# All lines in the docstring, expect the brief introduction.
for item in page_info.doc.docstring_parts:
parts.append(_format_docstring(item, table_title_template=None))
parts.append(_bottom_compat(page_info, h_level=2))
parts.append('\n\n')
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
if page_info.modules:
parts.append('## Modules\n\n')
parts.extend(
_build_module_parts(module_parts=page_info.modules,
template='[`{short_name}`]({url}) module'))
if page_info.classes:
parts.append('## Classes\n\n')
parts.extend(
_build_module_parts(module_parts=page_info.classes,
template='[`class {short_name}`]({url})'))
if page_info.functions:
parts.append('## Functions\n\n')
parts.extend(
_build_module_parts(module_parts=page_info.functions,
template='[`{short_name}(...)`]({url})'))
if page_info.type_alias:
parts.append('## Type Aliases\n\n')
parts.extend(
_build_module_parts(module_parts=page_info.type_alias,
template='[`{short_name}`]({url})'))
if page_info.other_members:
parts.append(
_other_members(
page_info.other_members,
title='<h2 class="add-link">Other Members</h2>',
))
return ''.join(parts)
def _build_module_page(page_info: parser.ModulePageInfo,
table_view: bool) -> str:
"""Constructs a markdown page given a `ModulePageInfo` object.
Args:
page_info: A `ModulePageInfo` object containing information that's used to
create a module page.
For example, see https://www.tensorflow.org/api_docs/python/tf/data
table_view: If True, `Args`, `Returns`, `Raises` or `Attributes` will be
converted to a tabular format while generating markdown. If False, they
will be converted to a markdown List view.
Returns:
The module markdown page.
"""
parts = [f'# Module: {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
# First line of the docstring i.e. a brief introduction about the symbol.
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
# All lines in the docstring, expect the brief introduction.
for item in page_info.doc.docstring_parts:
parts.append(_format_docstring(item, table_view, table_title_template=None))
parts.append(_build_compatibility(page_info.doc.compatibility))
parts.append('\n\n')
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
if page_info.modules:
parts.append('## Modules\n\n')
parts.extend(
_build_module_parts(
module_parts=page_info.modules,
template='[`{short_name}`]({url}) module'))
if page_info.classes:
parts.append('## Classes\n\n')
parts.extend(
_build_module_parts(
module_parts=page_info.classes,
template='[`class {short_name}`]({url})'))
if page_info.functions:
parts.append('## Functions\n\n')
parts.extend(
_build_module_parts(
module_parts=page_info.functions,
template='[`{short_name}(...)`]({url})'))
if page_info.type_alias:
parts.append('## Type Aliases\n\n')
parts.extend(
_build_module_parts(
module_parts=page_info.type_alias,
template='[`{short_name}`]({url})'))
if page_info.other_members:
# TODO(markdaoust): Document the value of the members, for basic types.
parts.append('## Other Members\n\n')
parts.append(_other_members(page_info.other_members))
return ''.join(parts)
def _build_class_page(page_info):
"""Given a ClassPageInfo object Return the page as an md string."""
parts = ['# {page_info.full_name}\n\n'.format(page_info=page_info)]
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
parts.append('## Class `{}`\n\n'.format(
page_info.full_name.split('.')[-1]))
parts.append(page_info.doc.brief + '\n\n')
if page_info.bases:
parts.append('Inherits From: ')
link_template = '[`{short_name}`]({url})'
parts.append(', '.join(
link_template.format(**base._asdict())
for base in page_info.bases))
parts.append('\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
# This will be replaced by the "Used in: <notebooks>" whenever it is run.
parts.append('<!-- Placeholder for "Used in" -->\n')
parts.extend(str(item) for item in page_info.doc.docstring_parts)
parts.append(_build_compatibility(page_info.doc.compatibility))
parts.append('\n\n')
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
method_info_dict = {
method.short_name: method
for method in page_info.methods
}
init_constructor = method_info_dict.pop('__init__', None)
new_constructor = method_info_dict.pop('__new__', None)
constructor = None
if init_constructor is not None:
constructor = init_constructor
elif new_constructor is not None:
constructor = new_constructor
if constructor is not None:
parts.append(_build_method_section(constructor, heading_level=2))
parts.append('\n\n')
if page_info.classes:
parts.append('## Child Classes\n')
link_template = ('[`class {class_info.short_name}`]'
'({class_info.url})\n\n')
class_links = sorted(
link_template.format(class_info=class_info)
for class_info in page_info.classes)
parts.extend(class_links)
if page_info.properties:
parts.append('## Properties\n\n')
for prop_info in page_info.properties:
h3 = (
f'<h3 id="{prop_info.short_name}"><code>{prop_info.short_name}'
'</code></h3>\n\n')
parts.append(h3)
parts.append(prop_info.doc.brief + '\n')
parts.extend(str(item) for item in prop_info.doc.docstring_parts)
parts.append(_build_compatibility(prop_info.doc.compatibility))
parts.append('\n\n')
parts.append('\n\n')
if method_info_dict:
parts.append('## Methods\n\n')
for _, method_info in sorted(method_info_dict.items()):
parts.append(_build_method_section(method_info))
parts.append('\n\n')
if page_info.other_members:
parts.append('## Class Members\n\n')
parts.append(_other_members(page_info.other_members))
return ''.join(parts)
def _build_module_page(page_info):
"""Given a ClassPageInfo object Return the page as an md string."""
parts = [f'# Module: {page_info.full_name}\n\n']
parts.append('<!-- Insert buttons and diff -->\n')
parts.append(_top_source_link(page_info.defined_in))
parts.append('\n\n')
# First line of the docstring i.e. a brief introduction about the symbol.
parts.append(page_info.doc.brief + '\n\n')
parts.append(_build_collapsable_aliases(page_info.aliases))
# All lines in the docstring, expect the brief introduction.
parts.extend(str(item) for item in page_info.doc.docstring_parts)
parts.append(_build_compatibility(page_info.doc.compatibility))
parts.append('\n\n')
custom_content = doc_controls.get_custom_page_content(page_info.py_object)
if custom_content is not None:
parts.append(custom_content)
return ''.join(parts)
if page_info.modules:
parts.append('## Modules\n\n')
template = '[`{short_name}`]({url}) module'
for item in page_info.modules:
parts.append(template.format(**item._asdict()))
if item.doc.brief:
parts.append(': ' + item.doc.brief)
parts.append('\n\n')
if page_info.classes:
parts.append('## Classes\n\n')
template = '[`class {short_name}`]({url})'
for item in page_info.classes:
parts.append(template.format(**item._asdict()))
if item.doc.brief:
parts.append(': ' + item.doc.brief)
parts.append('\n\n')
if page_info.functions:
parts.append('## Functions\n\n')
template = '[`{short_name}(...)`]({url})'
for item in page_info.functions:
parts.append(template.format(**item._asdict()))
if item.doc.brief:
parts.append(': ' + item.doc.brief)
parts.append('\n\n')
if page_info.other_members:
# TODO(markdaoust): Document the value of the members,
# at least for basic types.
parts.append('## Other Members\n\n')
parts.append(_other_members(page_info.other_members))
return ''.join(parts)
