✨ feat: basic example parser

src/dokyu/parser/docstring/args.py

@@ -1,5 +1,5 @@
 # pyright: basic
-# pyright: reportUndefinedVariable=false
+
 
 from typing import Any
 

src/dokyu/parser/docstring/examples.py

@@ -0,0 +1,38 @@
+# pyright: basic
+
+
+from typing import Any
+
+from parsita import Parser, ParserContext, lit, opt, reg, rep, success
+
+from dokyu.parser.docstring.utils import double_indent, identifiers, indent
+from dokyu.schema.docstring import Example
+
+
+def to_example_code(example_code_lines: list[Any]) -> Parser[str, str]:
+    return success("\n".join(example_code_lines))
+
+
+def to_examples(examples_raw: list[Any]) -> Parser[str, list[Example]]:
+    examples = []
+    for example_info in examples_raw:
+        lang_, label_, code = example_info
+        lang = lang_.strip()
+        label = label_.strip() if label_ else None
+        examples.append(Example(description=None, lang=lang, label=label, code=code))
+    return success(examples)
+
+
+class ExamplesParser(ParserContext, whitespace=None):
+    next_line = lit("\n") & indent
+    blank_line = lit("\n")
+    examples_head = lit("Examples:")
+    example_code_block_head = indent >> reg(r".. code-block::\s*") >> identifiers << lit("\n")
+    # example_code_block_description = rep(double_indent >> reg(r".*") << lit("\n"))
+    example_code_block_label = opt(double_indent >> reg(r":name:\s*") >> reg(r".+") << lit("\n"))
+    example_code_block_body = (
+        rep((double_indent >> reg(r".+") << lit("\n")) | (lit("") << blank_line)) >= to_example_code
+    )
+    example_code_block = example_code_block_head & example_code_block_label << blank_line & example_code_block_body
+    examples_body = lit("\n") >> rep(example_code_block << rep(blank_line))
+    examples = examples_head >> examples_body >= to_examples

src/dokyu/parser/docstring/returns.py

@@ -1,11 +1,10 @@
 # pyright: basic
-# pyright: reportUndefinedVariable=false
 
 from typing import Any
 
 from parsita import Parser, ParserContext, lit, opt, reg, rep, success
 
-from dokyu.parser.docstring.utils import double_indent, identifiers, indent, optional_whitespace
+from dokyu.parser.docstring.utils import double_indent, indent, optional_whitespace
 from dokyu.schema.docstring import Return
 
 

src/dokyu/schema/docstring.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Optional, Union
 
 from pydantic import BaseModel
 
@@ -13,3 +13,25 @@ class Argument(BaseModel):
 class Return(BaseModel):
     type: Optional[str]
     description: str
+
+
+class Example(BaseModel):
+    lang: str
+    description: Optional[str]
+    label: Optional[str]
+    code: str
+
+
+class Warning(BaseModel):
+    content: str
+
+
+class Note(BaseModel):
+    content: str
+
+
+class Docstring(BaseModel):
+    description: list[Union[str, Warning, Note]]
+    args: list[Argument]
+    returns: Optional[Return]
+    examples: list[Example]

tests/test_parser/test_docstring/test_examples.py

@@ -0,0 +1,45 @@
+# pyright: basic
+
+import pytest
+from parsita import Success
+
+from dokyu.parser.docstring.examples import ExamplesParser
+from dokyu.schema.docstring import Example
+
+
+@pytest.mark.parametrize(
+    ("examples_string", "expected"),
+    [
+        (
+            """\
+Examples:
+    .. code-block:: python
+
+        >>> import paddle
+
+        >>> a = paddle.to_tensor(1)
+        >>> b = paddle.to_tensor(2)
+        >>> paddle.add(a, b)
+        Tensor(shape=[], dtype=int64, place=CPUPlace, stop_gradient=True)
+""",
+            [
+                Example(
+                    description=None,
+                    lang="python",
+                    label=None,
+                    code="""\
+>>> import paddle
+
+>>> a = paddle.to_tensor(1)
+>>> b = paddle.to_tensor(2)
+>>> paddle.add(a, b)
+Tensor(shape=[], dtype=int64, place=CPUPlace, stop_gradient=True)""",
+                )
+            ],
+        ),
+    ],
+)
+def test_parse_returns(examples_string: str, expected: list[Example]):
+    res = ExamplesParser.examples.parse(examples_string)
+    assert isinstance(res, Success)
+    assert res.unwrap() == expected