pydoctor.napoleon.docstring.GoogleDocstring

class documentation

class GoogleDocstring: (source)

Known subclasses: pydoctor.napoleon.docstring.NumpyDocstring

Convert Google style docstrings to reStructuredText.

Example

>>> from pydoctor.napoleon import GoogleDocstring
>>> docstring = '''One line summary.
...
... Extended description.
...
... Args:
...   arg1(int): Description of `arg1`
...   arg2(str): Description of `arg2`
... Returns:
...   str: Description of return value.
... '''
>>> print(GoogleDocstring(docstring))
One line summary.

Extended description.

:param arg1: Description of `arg1`
:type arg1: int
:param arg2: Description of `arg2`
:type arg2: str

:returns: Description of return value.
:returntype: str
>>> print(GoogleDocstring(docstring, process_type_fields=True))
One line summary.

Extended description.

:param arg1: Description of `arg1`
:type arg1: `int`
:param arg2: Description of `arg2`
:type arg2: `str`

:returns: Description of return value.
:returntype: `str`

Method	`__init__`	No summary
Method	`__str__`	Return the parsed docstring in reStructuredText format.
Method	`lines`	Return the parsed lines of the docstring in reStructuredText format.
Instance Variable	`warnings`	Warning messages triggered during the conversion.
Method	`_consume_contiguous`	Undocumented
Method	`_consume_empty`	Undocumented
Method	`_consume_field`	Undocumented
Method	`_consume_fields`	Undocumented
Method	`_consume_indented_block`	Undocumented
Method	`_consume_inline_attribute`	Undocumented
Method	`_consume_returns_section`	Undocumented
Method	`_consume_section_header`	Undocumented
Method	`_consume_to_end`	Undocumented
Method	`_consume_to_next_section`	Undocumented
Method	`_convert_type`	Tokenize the string type and convert it with additional markup and auto linking, with L{TypeDocstring}.
Method	`_dedent`	Undocumented
Method	`_escape_args_and_kwargs`	Undocumented
Method	`_fix_field_desc`	Undocumented
Method	`_format_admonition`	Undocumented
Method	`_format_block`	Undocumented
Method	`_format_docutils_params`	Undocumented
Method	`_format_field`	Undocumented
Method	`_format_fields`	Undocumented
Method	`_get_current_indent`	Undocumented
Method	`_get_indent`	Undocumented
Method	`_get_initial_indent`	Undocumented
Method	`_get_min_indent`	Undocumented
Method	`_indent`	Undocumented
Method	`_is_indented`	Undocumented
Method	`_is_list`	Undocumented
Method	`_is_section_break`	Undocumented
Method	`_is_section_header`	Undocumented
Method	`_parse`	Undocumented
Method	`_parse_admonition`	Undocumented
Method	`_parse_attribute_docstring`	Undocumented
Method	`_parse_attributes_section`	Undocumented
Method	`_parse_examples_section`	Undocumented
Method	`_parse_generic_section`	Undocumented
Method	`_parse_keyword_arguments_section`	Undocumented
Method	`_parse_methods_section`	Undocumented
Method	`_parse_notes_section`	Undocumented
Method	`_parse_parameters_section`	Undocumented
Method	`_parse_raises_section`	Undocumented
Method	`_parse_references_section`	Undocumented
Method	`_parse_returns_section`	Undocumented
Method	`_parse_see_also_section`	Undocumented
Method	`_parse_warns_section`	Undocumented
Method	`_partition_field_on_colon`	Undocumented
Method	`_partition_multiline_field_on_colon`	Partition multiple lines on colon. If the type or name span multiple lines, they will be automatically joined.
Method	`_strip_empty`	Undocumented
Class Variable	`_name_rgx`	Undocumented
Instance Variable	`_is_attribute`	Undocumented
Instance Variable	`_is_in_section`	Undocumented
Instance Variable	`_line_iter`	Undocumented
Instance Variable	`_parsed_lines`	Undocumented
Instance Variable	`_process_type_fields`	Undocumented
Instance Variable	`_section_indent`	Undocumented
Instance Variable	`_sections`	Undocumented

def __init__(self, docstring, is_attribute=False, process_type_fields=False): (source) ¶

Parameters
docstring:`str` or `list` of `str`	The docstring to parse, given either as a string or split into individual lines.
is_attribute:`bool`	If the documented object is an attribute, it will use the `_parse_attribute_docstring` method.
process_type_fields:`bool`	Whether to process the type fields or to leave them untouched (default) in order to be processed later. Value `process_type_fields=False` is currently only used in the tests.

def __str__(self): (source) ¶

Return the parsed docstring in reStructuredText format.

Returns
`str`	Unicode version of the docstring.

def lines(self): (source) ¶

Return the parsed lines of the docstring in reStructuredText format.

Returns
`list(str)`	The lines of the docstring in a list.

warnings: List[Tuple[str, int]] = (source) ¶

Warning messages triggered during the conversion.

def _consume_contiguous(self): (source) ¶

Undocumented

Returns
`List[str]`	Undocumented

def _consume_empty(self): (source) ¶

Undocumented

Returns
`List[str]`	Undocumented

def _consume_field(self, parse_type=True, prefer_type=False, **kwargs): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Parameters
parse_type:`bool`	Undocumented
prefer_type:`bool`	Undocumented
**kwargs:`Any`	Undocumented
Returns
`Field`	Undocumented

def _consume_fields(self, parse_type=True, prefer_type=False, multiple=False, **kwargs): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Parameters
parse_type:`bool`	Undocumented
prefer_type:`bool`	Undocumented
multiple:`bool`	Undocumented
**kwargs:`Any`	Undocumented
Returns
`List[Field]`	Undocumented

def _consume_indented_block(self, indent=1): (source) ¶

Undocumented

Parameters
indent:`int`	Undocumented
Returns
`List[str]`	Undocumented

def _consume_inline_attribute(self): (source) ¶

Undocumented

Returns
`Tuple[str, List[str]]`	Undocumented

def _consume_returns_section(self): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Returns
`List[Field]`	Undocumented

def _consume_section_header(self): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Returns
`str`	Undocumented

def _consume_to_end(self): (source) ¶

Undocumented

Returns
`List[str]`	Undocumented

def _consume_to_next_section(self): (source) ¶

Undocumented

Returns
`List[str]`	Undocumented

def _convert_type(self, _type, is_type_field=True, lineno=0): (source) ¶

Tokenize the string type and convert it with additional markup and auto linking, with L{TypeDocstring}.

Parameters
_type:`bool`	the string type to convert.
is_type_field:`bool`	Whether the string is the content of a `:type:` or `rtype` field. If this is `True` and `GoogleDocstring`'s `process_type_fields` is `False` (defaults), the type will NOT be converted (instead, it's returned as is) because it will be converted by the code provided by `ParsedTypeDocstring` class in a later stage of docstring parsing.
lineno:`int`	Undocumented
Returns
`str`	Undocumented

def _dedent(self, lines, full=False): (source) ¶

Undocumented

Parameters
lines:`List[str]`	Undocumented
full:`bool`	Undocumented
Returns
`List[str]`	Undocumented

def _escape_args_and_kwargs(self, name): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Parameters
name:`str`	Undocumented
Returns
`str`	Undocumented

def _fix_field_desc(self, desc): (source) ¶

Undocumented

Parameters
desc:`List[str]`	Undocumented
Returns
`List[str]`	Undocumented

def _format_admonition(self, admonition, lines): (source) ¶

Undocumented

Parameters
admonition:`str`	Undocumented
lines:`List[str]`	Undocumented
Returns
`List[str]`	Undocumented

def _format_block(self, prefix, lines, padding=''): (source) ¶

Undocumented

Parameters
prefix:`str`	Undocumented
lines:`List[str]`	Undocumented
padding:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _format_docutils_params(self, fields, field_role='param', type_role='type'): (source) ¶

Undocumented

Parameters
fields:`List[Field]`	Undocumented
field_role:`str`	Undocumented
type_role:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _format_field(self, _name, _type, _desc, lineno=0): (source) ¶

Undocumented

Parameters
_name:`str`	Undocumented
_type:`str`	Undocumented
_desc:`List[str]`	Undocumented
lineno:`int`	Undocumented
Returns
`List[str]`	Undocumented

def _format_fields(self, field_type, fields): (source) ¶

Undocumented

Parameters
field_type:`str`	Undocumented
fields:`List[Field]`	Undocumented
Returns
`List[str]`	Undocumented

def _get_current_indent(self, peek_ahead=0): (source) ¶

Undocumented

Parameters
peek_ahead:`int`	Undocumented
Returns
`int`	Undocumented

def _get_indent(self, line): (source) ¶

Undocumented

Parameters
line:`str`	Undocumented
Returns
`int`	Undocumented

def _get_initial_indent(self, lines): (source) ¶

Undocumented

Parameters
lines:`List[str]`	Undocumented
Returns
`int`	Undocumented

def _get_min_indent(self, lines): (source) ¶

Undocumented

Parameters
lines:`List[str]`	Undocumented
Returns
`int`	Undocumented

def _indent(self, lines, n=4): (source) ¶

Undocumented

Parameters
lines:`List[str]`	Undocumented
n:`int`	Undocumented
Returns
`List[str]`	Undocumented

def _is_indented(self, line, indent=1): (source) ¶

Undocumented

Parameters
line:`str`	Undocumented
indent:`int`	Undocumented
Returns
`bool`	Undocumented

def _is_list(self, lines): (source) ¶

Undocumented

Parameters
lines:`List[str]`	Undocumented
Returns
`bool`	Undocumented

def _is_section_break(self): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Returns
`bool`	Undocumented

def _is_section_header(self): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Returns
`bool`	Undocumented

def _parse(self): (source) ¶

Undocumented

def _parse_admonition(self, admonition, section): (source) ¶

Undocumented

Parameters
admonition:`str`	Undocumented
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_attribute_docstring(self): (source) ¶

Undocumented

Returns
`List[str]`	Undocumented

def _parse_attributes_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_examples_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_generic_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_keyword_arguments_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_methods_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_notes_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_parameters_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_raises_section(self, section, field_type='raises', prefer_type=True): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
field_type:`str`	Undocumented
prefer_type:`bool`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_references_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_returns_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_see_also_section(self, section): (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _parse_warns_section(self, section): (source) ¶

Undocumented

Parameters
section:`str`	Undocumented
Returns
`List[str]`	Undocumented

def _partition_field_on_colon(self, line): (source) ¶

Undocumented

Parameters
line:`str`	Undocumented
Returns
`Tuple[str, str, str]`	Undocumented

def _partition_multiline_field_on_colon(self, lines, format_validator): (source) ¶

Partition multiple lines on colon. If the type or name span multiple lines, they will be automatically joined.

Parameters
lines:`List[str]`	Lines to split
format_validator:`Callable[[str], bool]`	Validator returning `bool` indicates if the value of before_colon is sane. If the value is not sane, fall back to `_partition_field_on_colon` behaviour with a warning. Note The validator will be called with a one line string as the argument. Note Only used for multiline fields.
Returns
`Tuple[str, str, List[str]]`	before_colon: `str` - depending on the context this might be the first line of the description or the name with the optional type or the type. colon: `str` description: `list`(`str`) - Can contains lines with only white spaces.

def _strip_empty(self, lines): (source) ¶

Undocumented

Parameters
lines:`List[str]`	Undocumented
Returns
`List[str]`	Undocumented

_name_rgx = (source) ¶

Undocumented

_is_attribute = (source) ¶

Undocumented

_is_in_section: bool = (source) ¶

Undocumented

_line_iter: modify_iter[str] = (source) ¶

Undocumented

_parsed_lines = (source) ¶

Undocumented

_process_type_fields = (source) ¶

Undocumented

_section_indent = (source) ¶

Undocumented

_sections: Dict[str, Callable[[str], List[str]]] = (source) ¶

Undocumented