pydoctor.napoleon.docstring.GoogleDocstring

class documentation

class GoogleDocstring: (source)

Known subclasses: pydoctor.napoleon.docstring.NumpyDocstring

Constructor: GoogleDocstring(docstring, what, process_type_fields)

Convert Google style docstrings to reStructuredText.

Example

>>> 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.
<BLANKLINE>
Extended description.
<BLANKLINE>
:param arg1: Description of `arg1`
:type arg1: int
:param arg2: Description of `arg2`
:type arg2: str
<BLANKLINE>
:returns: Description of return value.
:returntype: str
>>> print(GoogleDocstring(docstring, process_type_fields=True))
One line summary.
<BLANKLINE>
Extended description.
<BLANKLINE>
:param arg1: Description of `arg1`
:type arg1: `int`
:param arg2: Description of `arg2`
:type arg2: `str`
<BLANKLINE>
: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_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
Instance Variable	`_what`	Undocumented

def __init__(self, docstring: str | list[str], what: Literal['function', 'module', 'class', 'attribute'] | None = None, process_type_fields: bool = False): (source) ¶

Parameters
docstring:`str` or `list` of `str`	The docstring to parse, given either as a string or split into individual lines.
what:`Literal['function', 'module', 'class', 'attribute'] \| None`	Optional string representing the type of object we're documenting.
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) -> str: (source) ¶

Return the parsed docstring in reStructuredText format.

Returns
`str`	Unicode version of the docstring.

def lines(self) -> list[str]: (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) -> list[str]: (source) ¶

Undocumented

def _consume_empty(self) -> list[str]: (source) ¶

Undocumented

def _consume_field(self, parse_type: bool = True, prefer_type: bool = False, **kwargs: Any) -> Field: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _consume_fields(self, parse_type: bool = True, prefer_type: bool = False, multiple: bool = False, **kwargs: Any) -> list[Field]: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _consume_indented_block(self, indent: int = 1) -> list[str]: (source) ¶

Undocumented

def _consume_inline_attribute(self) -> tuple[str, list[str]]: (source) ¶

Undocumented

def _consume_returns_section(self) -> list[Field]: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _consume_section_header(self) -> str: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _consume_to_end(self) -> list[str]: (source) ¶

Undocumented

def _consume_to_next_section(self) -> list[str]: (source) ¶

Undocumented

def _convert_type(self, _type: str, is_type_field: bool = True, lineno: int = 0) -> str: (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: list[str], full: bool = False) -> list[str]: (source) ¶

Undocumented

def _escape_args_and_kwargs(self, name: str) -> str: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _fix_field_desc(self, desc: list[str]) -> list[str]: (source) ¶

Undocumented

def _format_admonition(self, admonition: str, lines: list[str]) -> list[str]: (source) ¶

Undocumented

def _format_block(self, prefix: str, lines: list[str], padding: str = '') -> list[str]: (source) ¶

Undocumented

def _format_docutils_params(self, fields: list[Field], field_role: str = 'param', type_role: str = 'type') -> list[str]: (source) ¶

Undocumented

def _format_field(self, _name: str, _type: str, _desc: list[str], lineno: int = 0) -> list[str]: (source) ¶

Undocumented

def _format_fields(self, field_type: str, fields: list[Field]) -> list[str]: (source) ¶

Undocumented

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

Undocumented

def _get_indent(self, line: str) -> int: (source) ¶

Undocumented

def _get_initial_indent(self, lines: list[str]) -> int: (source) ¶

Undocumented

def _get_min_indent(self, lines: list[str]) -> int: (source) ¶

Undocumented

def _indent(self, lines: list[str], n: int = 4) -> list[str]: (source) ¶

Undocumented

def _is_indented(self, line: str, indent: int = 1) -> bool: (source) ¶

Undocumented

def _is_list(self, lines: list[str]) -> bool: (source) ¶

Undocumented

def _is_section_break(self) -> bool: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _is_section_header(self) -> bool: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _parse(self): (source) ¶

Undocumented

def _parse_admonition(self, admonition: str, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_attribute_docstring(self) -> list[str]: (source) ¶

Undocumented

def _parse_attributes_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_examples_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_generic_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_keyword_arguments_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_methods_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_notes_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_parameters_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_raises_section(self, section: str, field_type: str = 'raises', prefer_type: bool = True) -> list[str]: (source) ¶

Undocumented

def _parse_references_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_returns_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _parse_see_also_section(self, section: str) -> list[str]: (source) ¶

overridden in pydoctor.napoleon.docstring.NumpyDocstring

Undocumented

def _parse_warns_section(self, section: str) -> list[str]: (source) ¶

Undocumented

def _partition_field_on_colon(self, line: str) -> tuple[str, str, str]: (source) ¶

Undocumented

def _partition_multiline_field_on_colon(self, lines: list[str], format_validator: Callable[[str], bool]) -> tuple[str, str, list[str]]: (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: list[str]) -> list[str]: (source) ¶

Undocumented

_name_rgx = (source) ¶

Undocumented

_is_in_section: bool = (source) ¶

Undocumented

_line_iter: modify_iter[str] = (source) ¶

Undocumented

_parsed_lines: list[str] = (source) ¶

Undocumented

_process_type_fields = (source) ¶

Undocumented

_section_indent: int = (source) ¶

Undocumented

_sections: dict[str, Callable[[str], list[str]]] = (source) ¶

Undocumented

_what = (source) ¶

Undocumented