feat: Support Google-style Yields sections

Issue #89: #89
PR #116: #116

Author: pawamoy

Diff for: src/pytkdocs/parsers/docstrings/base.py

@@ -105,6 +105,7 @@ class Type:
         PARAMETERS = "parameters"
         EXCEPTIONS = "exceptions"
         RETURN = "return"
+        YIELD = "yield"
         EXAMPLES = "examples"
         ATTRIBUTES = "attributes"
         KEYWORD_ARGS = "keyword_args"

Diff for: src/pytkdocs/parsers/docstrings/google.py

@@ -17,6 +17,8 @@
     "exceptions:": Section.Type.EXCEPTIONS,
     "return:": Section.Type.RETURN,
     "returns:": Section.Type.RETURN,
+    "yield:": Section.Type.YIELD,
+    "yields:": Section.Type.YIELD,
     "example:": Section.Type.EXAMPLES,
     "examples:": Section.Type.EXAMPLES,
     "attribute:": Section.Type.ATTRIBUTES,
@@ -46,6 +48,7 @@ def __init__(self, replace_admonitions: bool = True) -> None:
             Section.Type.EXAMPLES: self.read_examples_section,
             Section.Type.ATTRIBUTES: self.read_attributes_section,
             Section.Type.RETURN: self.read_return_section,
+            Section.Type.YIELD: self.read_yield_section,
         }
 
     def parse_sections(self, docstring: str) -> List[Section]:  # noqa: D102
@@ -418,6 +421,43 @@ def read_return_section(self, lines: List[str], start_index: int) -> Tuple[Optio
 
         return Section(Section.Type.RETURN, AnnotatedObject(annotation, description)), i
 
+    def read_yield_section(self, lines: List[str], start_index: int) -> Tuple[Optional[Section], int]:
+        """
+        Parse a "yields" section.
+
+        Arguments:
+            lines: The return block lines.
+            start_index: The line number to start at.
+
+        Returns:
+            A tuple containing a `Section` (or `None`) and the index at which to continue parsing.
+        """
+        text, i = self.read_block(lines, start_index)
+
+        # Early exit if there is no text in the yield section
+        if not text:
+            self.error(f"Empty yield section at line {start_index}")
+            return None, i
+
+        # First try to get the annotation and description from the docstring
+        try:
+            type_, text = text.split(":", 1)
+        except ValueError:
+            description = text
+            annotation = self.context["annotation"]
+            # If there was no annotation in the docstring then move to signature
+            if annotation is empty and self.context["signature"]:
+                annotation = self.context["signature"].return_annotation
+        else:
+            annotation = type_.lstrip()
+            description = text.lstrip()
+
+        # There was no type in the docstring and no annotation
+        if annotation is empty:
+            self.error("No yield type/annotation in docstring/signature")
+
+        return Section(Section.Type.YIELD, AnnotatedObject(annotation, description)), i
+
     def read_examples_section(self, lines: List[str], start_index: int) -> Tuple[Optional[Section], int]:
         """
         Parse an "examples" section.

Diff for: tests/test_parsers/test_docstrings/test_google.py

@@ -2,6 +2,7 @@
 
 import inspect
 from textwrap import dedent
+from typing import Iterator
 
 from pytkdocs.loader import Loader
 from pytkdocs.parsers.docstrings.base import Section
@@ -659,3 +660,41 @@ def test_parse_module_attributes_section():
         {"name": "E", "annotation": "float", "description": "Epsilon."},
     ]
     assert [serialize_attribute(attr) for attr in attr_section.value] == expected
+
+
+def test_docstring_with_yield_section():
+    """Parse Yields section."""
+
+    def f():
+        """A useless range wrapper.
+        
+        Yields:
+            int: Integers.
+        """
+        yield from range(10)
+
+    sections, errors = parse(inspect.getdoc(f), inspect.signature(f))
+    assert len(sections) == 2
+    annotated = sections[1].value
+    assert annotated.annotation is int
+    assert annotated.description == "Integers."
+    assert not errors
+
+
+def test_docstring_with_yield_section():
+    """Parse Yields section."""
+
+    def f() -> Iterator[int]:
+        """A useless range wrapper.
+        
+        Yields:
+            Integers.
+        """
+        yield from range(10)
+
+    sections, errors = parse(inspect.getdoc(f), inspect.signature(f))
+    assert len(sections) == 2
+    annotated = sections[1].value
+    assert annotated.annotation is Iterator[int]
+    assert annotated.description == "Integers."
+    assert not errors