diff --git a/src/griffe/docstrings/dataclasses.py b/src/griffe/docstrings/dataclasses.py index 6f5d7faa..ec95c71f 100644 --- a/src/griffe/docstrings/dataclasses.py +++ b/src/griffe/docstrings/dataclasses.py @@ -11,26 +11,32 @@ class DocstringSectionKind(enum.Enum): text = "text" arguments = "arguments" + keyword_arguments = "keyword arguments" raises = "raises" + warns = "warns" returns = "returns" yields = "yields" + receives = "receives" examples = "examples" attributes = "attributes" - keyword_arguments = "keyword arguments" + deprecated = "deprecated" + admonition = "admonition" class DocstringSection: """Placeholder.""" - def __init__(self, kind: DocstringSectionKind, value: Any) -> None: + def __init__(self, kind: DocstringSectionKind, value: Any, title: str | None = None) -> None: """Initialize the section. Arguments: kind: The section kind. value: The section value. + title: An optional title. """ self.kind: DocstringSectionKind = kind self.value: Any = value + self.title: str | None = title def as_dict(self, **kwargs) -> dict[str, Any]: """Return this section's data as a dictionary. @@ -45,7 +51,43 @@ def as_dict(self, **kwargs) -> dict[str, Any]: serialized_value = self.value.as_dict(**kwargs) else: serialized_value = self.value - return {"kind": self.kind.value, "value": serialized_value} + base = {"kind": self.kind.value, "value": serialized_value} + if self.title: + base["title"] = self.title + return base + + +class DocstringAdmonition: + """This base class represents admonitions. + + Attributes: + kind: The admonition kind. + contents: The admonition contents. + """ + + def __init__(self, *, kind: str, contents: str) -> None: + """Initialize the admonition. + + Arguments: + kind: The admonition kind. + contents: The admonition contents. + """ + self.kind: str = kind + self.contents: str = contents + + def as_dict(self, **kwargs) -> dict[str, Any]: + """Return this admonition's data as a dictionary. + + Arguments: + **kwargs: Additional serialization options. + + Returns: + A dictionary. + """ + return { + "kind": self.kind, + "contents": self.contents, + } class DocstringElement: @@ -93,6 +135,18 @@ class DocstringYield(DocstringElement): """This class represents a documented yield value.""" +class DocstringReceive(DocstringElement): + """This class represents a documented receive value.""" + + +class DocstringRaise(DocstringElement): + """This class represents a documented raise value.""" + + +class DocstringWarn(DocstringElement): + """This class represents a documented warn value.""" + + class DocstringNamedElement(DocstringElement): """This base class represents annotated, named elements.