fix: Use already parsed docstring sections when dumping full data

Deprecate the docstring parameters passed to the JSON encoder.

Discussion griffe-typingdoc#6: mkdocstrings/griffe-typingdoc#6

Author: pawamoy

src/griffe/dataclasses.py

@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import inspect
+import warnings
 from collections import defaultdict
 from contextlib import suppress
 from pathlib import Path
@@ -134,24 +135,34 @@ def parse(
         """
         return parse(self, parser or self.parser, **(options or self.parser_options))
 
-    def as_dict(self, *, full: bool = False, docstring_parser: Parser | None = None, **kwargs: Any) -> dict[str, Any]:
+    def as_dict(
+        self,
+        *,
+        full: bool = False,
+        docstring_parser: Parser | None = None,
+        **kwargs: Any,  # noqa: ARG002
+    ) -> dict[str, Any]:
         """Return this docstring's data as a dictionary.
 
         Parameters:
             full: Whether to return full info, or just base info.
-            docstring_parser: The docstring parser to parse the docstring with. By default, no parsing is done.
-            **kwargs: Additional serialization or docstring parsing options.
+            docstring_parser: Deprecated. The docstring parser to parse the docstring with. By default, no parsing is done.
+            **kwargs: Additional serialization options.
 
         Returns:
             A dictionary.
         """
+        # TODO: Remove at some point.
+        if docstring_parser is not None:
+            warnings.warn("Parameter `docstring_parser` is deprecated and has no effect.", stacklevel=1)
+
         base: dict[str, Any] = {
             "value": self.value,
             "lineno": self.lineno,
             "endlineno": self.endlineno,
         }
         if full:
-            base["parsed"] = self.parse(docstring_parser, **kwargs)
+            base["parsed"] = self.parsed
         return base
 
 

src/griffe/encoders.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import json
+import warnings
 from pathlib import Path, PosixPath, WindowsPath
 from typing import TYPE_CHECKING, Any, Callable
 
@@ -82,14 +83,20 @@ def __init__(
                 you don't need the full data as it can be infered again
                 using the base data. If you want to feed a non-Python
                 tool instead, dump the full data.
-            docstring_parser: The docstring parser to use. By default, no parsing is done.
-            docstring_options: Additional docstring parsing options.
+            docstring_parser: Deprecated. The docstring parser to use. By default, no parsing is done.
+            docstring_options: Deprecated. Additional docstring parsing options.
             **kwargs: See [`json.JSONEncoder`][].
         """
         super().__init__(*args, **kwargs)
         self.full: bool = full
+
+        # TODO: Remove at some point.
         self.docstring_parser: Parser | None = docstring_parser
         self.docstring_options: dict[str, Any] = docstring_options or {}
+        if docstring_parser is not None:
+            warnings.warn("Parameter `docstring_parser` is deprecated and has no effect.", stacklevel=1)
+        if docstring_options is not None:
+            warnings.warn("Parameter `docstring_options` is deprecated and has no effect.", stacklevel=1)
 
     def default(self, obj: Any) -> Any:
         """Return a serializable representation of the given object.
@@ -101,7 +108,7 @@ def default(self, obj: Any) -> Any:
             A serializable representation.
         """
         try:
-            return obj.as_dict(full=self.full, docstring_parser=self.docstring_parser, **self.docstring_options)
+            return obj.as_dict(full=self.full)
         except AttributeError:
             return _json_encoder_map.get(type(obj), super().default)(obj)