tfdocs.parser.TitleBlock

A class to parse title blocks (like Args:) and convert them to markdown.

tfdocs.parser.TitleBlock(
    title: Optional[str], text: str, items: Iterable[Tuple[str, str]]
)

This handles the "Args/Returns/Raises" blocks and anything similar.

These are used to extract metadata (argument descriptions, etc), and upgrade This TitleBlock to markdown.

These blocks are delimited by indentation. There must be a blank line before the first TitleBlock in a series.

The expected format is:

Title:
  Freeform text
  arg1: value1
  arg2: value1

These are represented as:

TitleBlock(
  title = "Arguments",
  text = "Freeform text",
  items=[('arg1', 'value1'), ('arg2', 'value2')])

The "text" and "items" fields may be empty. When both are empty the generated markdown only serves to upgrade the title to a

.

title The title line, without the colon.
text Freeform text. Anything between the title, and the items.
items A list of (name, value) string pairs. All items must have the same indentation.

Methods

split_string

View source

@classmethod
split_string(
    docstring: str
)

Given a docstring split it into a list of str or TitleBlock chunks.

For example the docstring of tf.nn.relu:

''' Computes max(features, 0).

Args
features A Tensor. Must be one of the following types: float32, float64, int32, int64, uint8, int16, int8, uint16, half.
name A name for the operation (optional).

More freeform markdown text. '''

This is parsed, and returned as:

[
    "Computes rectified linear: `max(features, 0)`.",
    TitleBlock(
      title='Args',
      text='',
      items=[
        ('features', ' A `Tensor`. Must be...'),
        ('name', ' A name for the operation (optional).\n\n')]
    ),
    "More freeform markdown text."
]

Args: docstring: The docstring to parse

Returns
The docstring split into chunks. Each chunk produces valid markdown when str is called on it (each chunk is a python str, or a TitleBlock).

table_view

View source

table_view(
    title_template: Optional[str] = None, anchors: bool = True
) -> str

Returns the TitleBlock as an HTML table.

Args
title_template Template for title detailing how to display it.

Returns
Table containing the content to display.

__eq__

__eq__(
    other
)

BLOCK_RE Instance of re.Pattern
ITEM_RE Instance of re.Pattern