google: support Example section

Author: yewentao

docstring_parser/common.py

@@ -15,6 +15,7 @@
 DEPRECATION_KEYWORDS = {"deprecation", "deprecated"}
 RETURNS_KEYWORDS = {"return", "returns"}
 YIELDS_KEYWORDS = {"yield", "yields"}
+EXAMPLES_KEYWORDS = {"example", "examples"}
 
 
 class ParseError(RuntimeError):
@@ -130,6 +131,19 @@ def __init__(
         self.description = description
 
 
+class DocstringExample(DocstringMeta):
+    """DocstringMeta symbolizing example metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        description: T.Optional[str],
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.description = description
+
+
 class Docstring:
     """Docstring object representation."""
 
@@ -184,3 +198,10 @@ def deprecation(self) -> T.Optional[DocstringDeprecated]:
             if isinstance(item, DocstringDeprecated):
                 return item
         return None
+
+    @property
+    def examples(self) -> T.List[DocstringExample]:
+        """Return a list of information on function examples."""
+        return [
+            item for item in self.meta if isinstance(item, DocstringExample)
+        ]

docstring_parser/google.py

@@ -7,11 +7,13 @@
 from enum import IntEnum
 
 from .common import (
+    EXAMPLES_KEYWORDS,
     PARAM_KEYWORDS,
     RAISES_KEYWORDS,
     RETURNS_KEYWORDS,
     YIELDS_KEYWORDS,
     Docstring,
+    DocstringExample,
     DocstringMeta,
     DocstringParam,
     DocstringRaises,
@@ -133,6 +135,8 @@ def _build_single_meta(section: Section, desc: str) -> DocstringMeta:
             return DocstringRaises(
                 args=[section.key], description=desc, type_name=None
             )
+        if section.key in EXAMPLES_KEYWORDS:
+            return DocstringExample(args=[section.key], description=desc)
         if section.key in PARAM_KEYWORDS:
             raise ParseError("Expected paramenter name.")
         return DocstringMeta(args=[section.key], description=desc)

docstring_parser/tests/test_google.py

@@ -632,9 +632,9 @@ def test_examples() -> None:
             more here
         """
     )
-    assert len(docstring.meta) == 2
-    assert docstring.meta[0].description == "example: 1"
-    assert docstring.meta[1].description == "long example\n\nmore here"
+    assert len(docstring.examples) == 2
+    assert docstring.examples[0].description == "example: 1"
+    assert docstring.examples[1].description == "long example\n\nmore here"
 
 
 def test_broken_meta() -> None:
@@ -696,9 +696,9 @@ def test_empty_example() -> None:
         """
     )
 
-    assert len(docstring.meta) == 2
-    assert docstring.meta[0].args == ["examples"]
-    assert docstring.meta[0].description == ""
+    assert len(docstring.examples) == 1
+    assert docstring.examples[0].args == ["examples"]
+    assert docstring.examples[0].description == ""
 
 
 @pytest.mark.parametrize(