wip

Author: pawamoy

packages/griffelib/src/griffe/_internal/docstrings/models.py

@@ -18,33 +18,46 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from textwrap import indent
+from typing import TYPE_CHECKING, Any, Literal
 
 from griffe._internal.enumerations import DocstringSectionKind
 from griffe._internal.expressions import ExprTuple
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from typing import Any, Literal
 
     from griffe._internal.expressions import Expr
 
 
+DocstringStyle = Literal["google", "numpy", "sphinx", "auto"]
+"""The supported docstring styles (literal values of the Parser enumeration)."""
+
+
 # Elements -----------------------------------------------
 class DocstringElement:
     """This base class represents annotated, nameless elements."""
 
-    def __init__(self, *, description: str, annotation: str | Expr | None = None) -> None:
+    def __init__(self, *, description: str, annotation: str | Expr | None = None, hardcoded: bool = True) -> None:
         """Initialize the element.
 
         Parameters:
-            annotation: The element annotation, if any.
             description: The element description.
+            annotation: The element annotation, if any.
+            hardcoded: Whether the annotation was hardcoded into the docstring.
         """
         self.description: str = description
         """The element description."""
         self.annotation: str | Expr | None = annotation
         """The element annotation."""
+        self.hardcoded: bool = hardcoded
+        """Whether the annotation was hardcoded into the docstring.
+
+        It could have been obtained via other means (e.g. type hints).
+
+        This helps to determine whether the annotation should be included
+        when re-rendering a docstring section.
+        """
 
     def as_dict(self, **kwargs: Any) -> dict[str, Any]:  # noqa: ARG002
         """Return this element's data as a dictionary.
@@ -71,6 +84,7 @@ def __init__(
         description: str,
         annotation: str | Expr | None = None,
         value: str | Expr | None = None,
+        hardcoded: bool = True,
     ) -> None:
         """Initialize the element.
 
@@ -79,8 +93,9 @@ def __init__(
             description: The element description.
             annotation: The element annotation, if any.
             value: The element value, as a string.
+            hardcoded: Whether the annotation was hardcoded into the docstring.
         """
-        super().__init__(description=description, annotation=annotation)
+        super().__init__(description=description, annotation=annotation, hardcoded=hardcoded)
         self.name: str = name
         """The element name."""
         self.value: str | Expr | None = value
@@ -277,6 +292,12 @@ def as_dict(self, **kwargs: Any) -> dict[str, Any]:
             base["title"] = self.title
         return base
 
+    def render(self, style: DocstringStyle) -> str:
+        """Render the section as a string."""
+        raise NotImplementedError(
+            f"Rendering not implemented for sections '{self.__class__.__name__}' and style '{style}'"
+        )
+
 
 class DocstringSectionText(DocstringSection):
     """This class represents a text section."""
@@ -293,6 +314,10 @@ def __init__(self, value: str, title: str | None = None) -> None:
         super().__init__(title)
         self.value: str = value
 
+    def render(self, style: DocstringStyle) -> str:
+        """Render the section as a string."""
+        return self.value
+
 
 class DocstringSectionParameters(DocstringSection):
     """This class represents a parameters section."""
@@ -309,6 +334,23 @@ def __init__(self, value: list[DocstringParameter], title: str | None = None) ->
         super().__init__(title)
         self.value: list[DocstringParameter] = value
 
+    def render(self, style: DocstringStyle) -> str:
+        """Render the section as a string."""
+        return {
+            "google": self.render_google,
+            "numpy": self.render_numpy,
+            "sphinx": self.render_sphinx,
+        }.get(style, super().render)()
+
+    def render_google(self) -> str:
+        """Render the section in Google style."""
+        lines = ["Parameters:"]
+        for param in self.value:
+            annotation = f" ({param.annotation})" if param.annotation and param.hardcoded else ""
+            lines.append(f"    {param.name}{annotation}:")
+            lines.extend(indent(param.description, " " * 8).splitlines())
+        return "\n".join(lines)
+
 
 class DocstringSectionOtherParameters(DocstringSectionParameters):
     """This class represents an other parameters section."""

packages/griffelib/src/griffe/_internal/docstrings/parsers.py

@@ -19,11 +19,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any
 
 from griffe._internal.docstrings.auto import AutoOptions, parse_auto
 from griffe._internal.docstrings.google import GoogleOptions, parse_google
-from griffe._internal.docstrings.models import DocstringSection, DocstringSectionText
+from griffe._internal.docstrings.models import DocstringSection, DocstringSectionText, DocstringStyle
 from griffe._internal.docstrings.numpy import NumpyOptions, parse_numpy
 from griffe._internal.docstrings.sphinx import SphinxOptions, parse_sphinx
 from griffe._internal.enumerations import Parser
@@ -34,8 +34,6 @@
     from griffe._internal.models import Docstring
 
 
-DocstringStyle = Literal["google", "numpy", "sphinx", "auto"]
-"""The supported docstring styles (literal values of the Parser enumeration)."""
 DocstringOptions = GoogleOptions | NumpyOptions | SphinxOptions | AutoOptions
 """The options for each docstring style."""