From ce59b7dca69e3a9946a0735405535e296e0ec9c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= <pawamoy@pm.me>
Date: Sun, 20 Aug 2023 11:12:40 +0200
Subject: [PATCH] feat: Allow passing a docstring parser name instead of its
 enumeration value

---
 src/griffe/dataclasses.py        | 12 ++++++++----
 src/griffe/docstrings/parsers.py | 10 ++++++++--
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/griffe/dataclasses.py b/src/griffe/dataclasses.py
index 5a99aa70..1cb867d2 100644
--- a/src/griffe/dataclasses.py
+++ b/src/griffe/dataclasses.py
@@ -11,7 +11,7 @@
 from contextlib import suppress
 from pathlib import Path
 from textwrap import dedent
-from typing import TYPE_CHECKING, Any, Callable, Sequence, Union, cast
+from typing import TYPE_CHECKING, Any, Callable, Literal, Sequence, Union, cast
 
 from griffe.c3linear import c3linear_merge
 from griffe.docstrings.parsers import Parser, parse
@@ -90,7 +90,7 @@ def __init__(
         lineno: int | None = None,
         endlineno: int | None = None,
         parent: Object | None = None,
-        parser: Parser | None = None,
+        parser: Literal["google", "numpy", "sphinx"] | Parser | None = None,
         parser_options: dict[str, Any] | None = None,
     ) -> None:
         """Initialize the docstring.
@@ -107,7 +107,7 @@ def __init__(
         self.lineno: int | None = lineno
         self.endlineno: int | None = endlineno
         self.parent: Object | None = parent
-        self.parser: Parser | None = parser
+        self.parser: Literal["google", "numpy", "sphinx"] | Parser | None = parser
         self.parser_options: dict[str, Any] = parser_options or {}
 
     def __bool__(self) -> bool:
@@ -131,7 +131,11 @@ def parsed(self) -> list[DocstringSection]:
         """
         return self.parse()
 
-    def parse(self, parser: Parser | None = None, **options: Any) -> list[DocstringSection]:
+    def parse(
+        self,
+        parser: Literal["google", "numpy", "sphinx"] | Parser | None = None,
+        **options: Any,
+    ) -> list[DocstringSection]:
         """Parse the docstring into structured data.
 
         Parameters:
diff --git a/src/griffe/docstrings/parsers.py b/src/griffe/docstrings/parsers.py
index d55db9b9..2a944da8 100644
--- a/src/griffe/docstrings/parsers.py
+++ b/src/griffe/docstrings/parsers.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 from griffe.docstrings.dataclasses import DocstringSection, DocstringSectionText
 from griffe.docstrings.google import parse as parse_google
@@ -20,7 +20,11 @@
 }
 
 
-def parse(docstring: Docstring, parser: Parser | None, **options: Any) -> list[DocstringSection]:
+def parse(
+    docstring: Docstring,
+    parser: Literal["google", "numpy", "sphinx"] | Parser | None,
+    **options: Any,
+) -> list[DocstringSection]:
     """Parse the docstring.
 
     Parameters:
@@ -32,6 +36,8 @@ def parse(docstring: Docstring, parser: Parser | None, **options: Any) -> list[D
         A list of docstring sections.
     """
     if parser:
+        if isinstance(parser, str):
+            parser = Parser(parser)
         return parsers[parser](docstring, **options)  # type: ignore[operator]
     return [DocstringSectionText(docstring.value)]