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)