pydoctor.napoleon.docstring.GoogleDocstring

class documentation

class GoogleDocstring: (source)

Known subclasses: pydoctor.napoleon.docstring.NumpyDocstring

Constructor: GoogleDocstring(docstring, is_attribute, process_type_fields)

View In Hierarchy

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: str | list[str], is_attribute: bool = False, process_type_fields: bool = False): (source)
Parameters
docstring:str or list of strThe docstring to parse, given either as a string or split into individual lines.
is_attribute:boolIf the documented object is an attribute, it will use the _parse_attribute_docstring method.
process_type_fields:boolWhether 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
strUnicode 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:boolthe string type to convert.
is_type_field:boolWhether 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:intUndocumented
Returns
strUndocumented
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_attribute = (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 = (source)

Undocumented

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

Undocumented