refactor: Add DocstringStyle literal type to prepare docstring style …

…auto detection feature

Issue-5: #5

docs/reference/api/docstrings/parsers.md

@@ -10,6 +10,8 @@
 
 ::: griffe.parse_sphinx
 
+::: griffe.DocstringStyle
+
 ## **Advanced API**
 
 ::: griffe.Parser

src/_griffe/docstrings/parsers.py

@@ -14,7 +14,10 @@
 if TYPE_CHECKING:
  from _griffe.models import Docstring
 
-parsers = {
+DocstringStyle = Literal["google", "numpy", "sphinx"]
+"""The supported docstring styles (literal values of the Parser enumeration)."""
+parsers: dict[Parser, Callable[[Docstring], list[DocstringSection]]] = {
+ Parser.auto: parse_auto,
  Parser.google: parse_google,
  Parser.sphinx: parse_sphinx,
  Parser.numpy: parse_numpy,
@@ -23,7 +26,7 @@
 
 def parse(
  docstring: Docstring,
- parser: Literal["google", "numpy", "sphinx"] | Parser | None,
+ parser: DocstringStyle | Parser | None,
  **options: Any,
 ) -> list[DocstringSection]:
  """Parse the docstring.
@@ -37,7 +40,7 @@ def parse(
  A list of docstring sections.
  """
  if parser:
- if isinstance(parser, str):
+ if not isinstance(parser, Parser):
  parser = Parser(parser)
- return parsers[parser](docstring, **options) # type: ignore[operator]
+ return parsers[parser](docstring, **options)
  return [DocstringSectionText(docstring.value)]

src/_griffe/models.py

@@ -9,10 +9,10 @@
 from contextlib import suppress
 from pathlib import Path
 from textwrap import dedent
-from typing import TYPE_CHECKING, Any, Callable, Literal, Sequence, Union, cast
+from typing import TYPE_CHECKING, Any, Callable, Sequence, Union, cast
 
 from _griffe.c3linear import c3linear_merge
-from _griffe.docstrings.parsers import parse
+from _griffe.docstrings.parsers import DocstringStyle, parse
 from _griffe.enumerations import Kind, ParameterKind, Parser
 from _griffe.exceptions import AliasResolutionError, BuiltinModuleError, CyclicAliasError, NameResolutionError
 from _griffe.expressions import ExprCall, ExprName
@@ -83,7 +83,7 @@ def __init__(
  lineno: int | None = None,
  endlineno: int | None = None,
  parent: Object | None = None,
- parser: Literal["google", "numpy", "sphinx"] | Parser | None = None,
+ parser: DocstringStyle | Parser | None = None,
  parser_options: dict[str, Any] | None = None,
  ) -> None:
  """Initialize the docstring.
@@ -104,7 +104,7 @@ def __init__(
  """The ending line number of the docstring."""
  self.parent: Object | None = parent
  """The object this docstring is attached to."""
- self.parser: Literal["google", "numpy", "sphinx"] | Parser | None = parser
+ self.parser: DocstringStyle | Parser | None = parser
  """The selected docstring parser."""
  self.parser_options: dict[str, Any] = parser_options or {}
  """The configured parsing options."""
@@ -121,7 +121,7 @@ def parsed(self) -> list[DocstringSection]:
 
  def parse(
  self,
- parser: Literal["google", "numpy", "sphinx"] | Parser | None = None,
+ parser: DocstringStyle | Parser | None = None,
  **options: Any,
  ) -> list[DocstringSection]:
  """Parse the docstring into structured data.

src/griffe/__init__.py

@@ -97,7 +97,11 @@
  DocstringYield,
 )
 from _griffe.docstrings.numpy import parse_numpy
-from _griffe.docstrings.parsers import parse, parsers
+from _griffe.docstrings.parsers import (
+ DocstringStyle,
+ parse,
+ parsers,
+)
 from _griffe.docstrings.sphinx import parse_sphinx
 from _griffe.docstrings.utils import DocstringWarningCallable, docstring_warning, parse_docstring_annotation
 from _griffe.encoders import JSONEncoder, json_decoder
@@ -278,6 +282,7 @@
  "DocstringSectionText",
  "DocstringSectionWarns",
  "DocstringSectionYields",
+ "DocstringStyle",
  "DocstringWarn",
  # YORE: Bump 1: Remove line.
  "DocstringWarningCallable",