⬇️

docs/litedoc/docstring/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+
+@Time    : 2024/8/28 下午1:46
+@Author  : snowykami
+@Email   : snowykami@outlook.com
+@File    : __init__.py.py
+@Software: PyCharm
+"""

docs/litedoc/docstring/docstring.py

@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""
+Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved 
+
+@Time    : 2024/8/28 下午1:46
+@Author  : snowykami
+@Email   : snowykami@outlook.com
+@File    : docstring.py
+@Software: PyCharm
+"""
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from litedoc.i18n import get_text
+
+
+class Attr(BaseModel):
+    name: str
+    type: str = ""
+    desc: str = ""
+
+
+class Args(BaseModel):
+    name: str
+    type: str = ""
+    desc: str = ""
+
+
+class Return(BaseModel):
+    desc: str = ""
+
+
+class Exception_(BaseModel):
+    name: str
+    desc: str = ""
+
+
+class Raise(BaseModel):
+    exceptions: list[Exception_] = []
+
+
+class Example(BaseModel):
+    desc: str = ""
+    input: str = ""
+    output: str = ""
+
+
+class Docstring(BaseModel):
+    desc: str = ""
+    args: list[Args] = []
+    attrs: list[Attr] = []
+    return_: Optional[Return] = None
+    raise_: list[Exception_] = []
+    example: list[Example] = []
+
+    def add_desc(self, desc: str):
+        if self.desc == "":
+            self.desc = desc
+        else:
+            self.desc += "\n" + desc
+
+    def add_arg(self, name: str, type_: str = "", desc: str = ""):
+        self.args.append(Args(name=name, type=type_, desc=desc))
+
+    def add_attrs(self, name: str, type_: str = "", desc: str = ""):
+        self.attrs.append(Attr(name=name, type=type_, desc=desc))
+
+    def add_return(self, desc: str = ""):
+        self.return_ = Return(desc=desc)
+
+    def add_raise(self, name: str, desc: str = ""):
+        self.raise_.append(Exception_(name=name, desc=desc))
+
+    def add_example(self, desc: str = "", input_: str = "", output: str = ""):
+        self.example.append(Example(desc=desc, input=input_, output=output))
+
+    def reduction(self) -> str:
+        """
+        通过解析结果还原docstring
+        Args:
+
+        Returns:
+
+        """
+        ret = ""
+        ret += self.desc + "\n"
+        if self.args:
+            ret += "Args:\n"
+            for arg in self.args:
+                ret += f"    {arg.name}: {arg.type}\n        {arg.desc}\n"
+        if self.attrs:
+            ret += "Attributes:\n"
+            for attr in self.attrs:
+                ret += f"    {attr.name}: {attr.type}\n        {attr.desc}\n"
+        if self.return_:
+            ret += "Returns:\n"
+            ret += f"    {self.return_.desc}\n"
+
+        if self.raise_:
+            ret += "Raises:\n"
+            for exception in self.raise_:
+                ret += f"    {exception.name}\n        {exception.desc}\n"
+
+        if self.example:
+            ret += "Examples:\n"
+            for example in self.example:
+                ret += f"    {example.desc}\n        Input: {example.input}\n        Output: {example.output}\n"
+
+        return ret
+
+    def markdown(self, lang: str, indent: int = 4, is_classmethod: bool = False) -> str:
+        """
+        生成markdown文档
+        Args:
+            is_classmethod:
+            lang:
+            indent:
+
+        Returns:
+
+        """
+        PREFIX = "" * indent
+        ret = ""
+        # ret += self.desc + "\n\n"
+        # print(self.reduction())
+        # print(self.desc, self.return_)
+        # 单数属性
+        if self.desc:
+            ret += PREFIX + f"\n**{get_text(lang, 'desc')}**: {self.desc}\n"
+        if self.return_ is not None:
+            ret += PREFIX + f"\n**{get_text(lang, 'docstring.return')}**: {self.return_.desc}\n"
+
+        # 复数属性
+        if self.args:
+            ret += PREFIX + f"\n**{get_text(lang, 'docstring.args')}**:\n"
+            for arg in self.args:
+                ret += PREFIX + f"> - {arg.name}: {arg.type}  {arg.desc}\n"
+        if self.attrs:
+            ret += PREFIX + f"\n**{get_text(lang, 'docstring.attrs')}**:\n"
+            for attr in self.attrs:
+                ret += PREFIX + f"> - {attr.name}: {attr.type}  {attr.desc}\n"
+        if self.raise_:
+            ret += PREFIX + f"\n**{get_text(lang, 'docstring.raises')}**:\n"
+            for exception in self.raise_:
+                ret += PREFIX + f"> - {exception.name}  {exception.desc}\n"
+        if self.example:
+            ret += PREFIX + f"\n**{get_text(lang, 'docstring.example')}**:\n"
+            for example in self.example:
+                ret += PREFIX + f"  - {example.desc}\n>        **{get_text(lang, 'docs.input')}**: {example.input}\n>        **{get_text(lang, 'docs.output')}**: {example.output}\n"
+        return ret
+
+    def __str__(self):
+        return self.desc

docs/litedoc/docstring/parser.py

@@ -0,0 +1,192 @@
+"""
+Google docstring parser for Python.
+"""
+from typing import Optional
+
+from litedoc.docstring.docstring import Docstring
+
+
+class Parser:
+    ...
+
+
+class GoogleDocstringParser(Parser):
+    _tokens = {
+            "Args"       : "args",
+            "Arguments"  : "args",
+            "参数"       : "args",
+
+            "Return"     : "return",
+            "Returns"    : "return",
+            "返回"       : "return",
+
+            "Attribute"  : "attribute",
+            "Attributes" : "attribute",
+            "属性"       : "attribute",
+
+            "Raises"     : "raises",
+            "Raise"      : "raises",
+            "引发"       : "raises",
+
+            "Example"    : "example",
+            "Examples"   : "example",
+            "示例"       : "example",
+
+            "Yields"     : "yields",
+            "Yield"      : "yields",
+            "产出"       : "yields",
+
+            "Requires"   : "requires",
+            "Require"    : "requires",
+            "需要"       : "requires",
+
+            "FrontMatter": "front_matter",
+            "前言"       : "front_matter",
+    }
+
+    def __init__(self, docstring: str, indent: int = 4):
+        self.lines = docstring.splitlines()
+        self.indent = indent
+        self.lineno = 0  # Current line number
+        self.char = 0  # Current character position
+
+        self.docstring = Docstring()
+
+    def read_line(self, move: bool = True) -> str:
+        """
+        每次读取一行
+        Args:
+            move: 是否移动指针
+        Returns:
+        """
+        if self.lineno >= len(self.lines):
+            return ""
+        line = self.lines[self.lineno]
+        if move:
+            self.lineno += 1
+        return line
+
+    def match_token(self) -> Optional[str]:
+        """
+        解析下一行的token
+        Returns:
+
+        """
+        for token in self._tokens:
+            line = self.read_line(move=False)
+            if line.strip().startswith(token):
+                self.lineno += 1
+                return self._tokens[token]
+        return None
+
+    def parse_args(self):
+        """
+        依次解析后面的参数行，直到缩进小于等于当前行的缩进
+        """
+        while line := self.match_next_line():
+            if ":" in line:
+                name, desc = line.split(":", 1)
+                self.docstring.add_arg(name.strip(), desc.strip())
+            else:
+                self.docstring.add_arg(line.strip())
+
+    def parse_return(self):
+        """
+        解析返回值行
+        """
+        if line := self.match_next_line():
+            self.docstring.add_return(line.strip())
+
+    def parse_raises(self):
+        """
+        解析异常行
+        """
+        while line := self.match_next_line():
+            if ":" in line:
+                name, desc = line.split(":", 1)
+                self.docstring.add_raise(name.strip(), desc.strip())
+            else:
+                self.docstring.add_raise(line.strip())
+
+    def parse_example(self):
+        """
+        解析示例行
+        """
+        while line := self.match_next_line():
+            if ":" in line:
+                name, desc = line.split(":", 1)
+                self.docstring.add_example(name.strip(), desc.strip())
+            else:
+                self.docstring.add_example(line.strip())
+
+    def parse_attrs(self):
+        """
+        解析属性行
+        """
+        while line := self.match_next_line():
+            if ":" in line:
+                name, desc = line.split(":", 1)
+                self.docstring.add_attrs(name.strip(), desc.strip())
+            else:
+                self.docstring.add_attrs(line.strip())
+
+    def match_next_line(self) -> Optional[str]:
+        """
+        在一个子解析器中，解析下一行，直到缩进小于等于当前行的缩进
+        Returns:
+        """
+        line = self.read_line(move=False)
+        if line.startswith(" " * self.indent):
+            self.lineno += 1
+            return line[self.indent:]
+        else:
+            return None
+
+    def parse(self) -> Docstring:
+        """
+        逐行解析，直到遇到EOS
+
+        最开始未解析到的内容全部加入desc
+
+        Returns:
+
+        """
+        add_desc = True
+        while self.lineno < len(self.lines):
+            token = self.match_token()
+            if token is None and add_desc:
+                self.docstring.add_desc(self.lines[self.lineno].strip())
+
+            if token is not None:
+                add_desc = False
+
+            match token:
+                case "args":
+                    self.parse_args()
+                case "return":
+                    self.parse_return()
+                case "attribute":
+                    self.parse_attrs()
+                case "raises":
+                    self.parse_raises()
+                case "example":
+                    self.parse_example()
+                case _:
+                    self.lineno += 1
+
+        return self.docstring
+
+
+class NumpyDocstringParser(Parser):
+    ...
+
+
+class ReStructuredParser(Parser):
+    ...
+
+
+def parse(docstring: str, parser: str = "google", indent: int = 4) -> Docstring:
+    if parser == "google":
+        return GoogleDocstringParser(docstring, indent).parse()
+    else:
+        raise ValueError(f"Unknown parser: {parser}")