Add stub converter (#36)

Author: stefmolin

README.md

@@ -73,7 +73,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify

src/docstringify/cli.py

@@ -9,17 +9,27 @@
 
 from . import __doc__ as pkg_description
 from . import __version__
-from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
+from .converters import (
+    GoogleDocstringConverter,
+    NumpydocDocstringConverter,
+    StubDocstringConverter,
+)
 from .traversal import DocstringTransformer, DocstringVisitor
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
 
 PROG = __package__
-STYLES: dict[str, type[GoogleDocstringConverter] | type[NumpydocDocstringConverter]] = {
+STYLES: dict[
+    str,
+    type[GoogleDocstringConverter]
+    | type[NumpydocDocstringConverter]
+    | type[StubDocstringConverter],
+] = {
     'google': GoogleDocstringConverter,
     'numpydoc': NumpydocDocstringConverter,
+    'stub': StubDocstringConverter,
 }
 CLI_DEFAULTS = {'threshold': 1.0}
 

src/docstringify/converters/__init__.py

@@ -3,9 +3,11 @@
 from .base import DocstringConverter
 from .google import GoogleDocstringConverter
 from .numpydoc import NumpydocDocstringConverter
+from .stub import StubDocstringConverter
 
 __all__ = [
     'DocstringConverter',
     'GoogleDocstringConverter',
     'NumpydocDocstringConverter',
+    'StubDocstringConverter',
 ]

src/docstringify/converters/stub.py

@@ -0,0 +1,121 @@
+"""Stub docstring converter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..components import DESCRIPTION_PLACEHOLDER, Parameter
+from .base import DocstringConverter
+
+if TYPE_CHECKING:
+    from ..nodes.base import DocstringNode
+    from ..nodes.function import FunctionDocstringNode
+
+
+class StubDocstringConverter(DocstringConverter):
+    """
+    Class defining the DocstringConverter API for injecting ``__description__`` stubs only.
+
+    Parameters
+    ----------
+    quote : bool
+        Whether to surround the generated docstrings in triple quotes.
+    """
+
+    def __init__(self, quote: bool) -> None:
+        super().__init__(
+            parameters_section_template='', returns_section_template='', quote=quote
+        )
+
+    def to_function_docstring(
+        self, docstring_node: FunctionDocstringNode, indent: int
+    ) -> str:
+        """
+        Convert an AST node into a function docstring.
+
+        Parameters
+        ----------
+        docstring_node : FunctionDocstringNode
+            An instance of :class:`.FunctionDocstringNode`, which wraps an instance of
+            :class:`ast.FunctionDef` or :class:`ast.AsyncFunctionDef`, adding additional
+            context relevant for Docstringify.
+        indent : int
+            The number of spaces by which to indent the docstring.
+
+        Returns
+        -------
+        str
+            The function docstring.
+        """
+        return self.format_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)
+
+    def format_parameter(self, parameter: Parameter) -> str:
+        """
+        Convert a :class:`.Parameter` instance into an entry in the parameters section
+        of the docstring.
+
+        Parameters
+        ----------
+        parameter : Parameter
+            Information on the function parameter, including its name, type, and default
+            value (if it has one).
+
+        Returns
+        -------
+        str
+            An empty string.
+        """
+        return ''
+
+    def format_return(self, return_type: str | None) -> str:
+        """
+        Convert a return type into an entry in the returns section of the docstring.
+
+        Parameters
+        ----------
+        return_type : str | None
+            The return type name for the function. This will be either a string for the
+            name (e.g., ``list[str]``) or ``None``, if ``None`` is returned.
+
+        Returns
+        -------
+        str
+            An empty string.
+        """
+        return ''
+
+    def to_module_docstring(self, docstring_node: DocstringNode) -> str:
+        """
+        Convert an AST node into a module docstring.
+
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an instance of
+            :class:`ast.Module`, adding additional context relevant for Docstringify.
+
+        Returns
+        -------
+        str
+            The module docstring.
+        """
+        return self.format_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
+
+    def to_class_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
+        """
+        Convert an AST node into a class docstring.
+
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an instance of
+            :class:`ast.ClassDef`, adding additional context relevant for Docstringify.
+        indent : int
+            The number of spaces by which to indent the docstring.
+
+        Returns
+        -------
+        str
+            The class docstring.
+        """
+        return self.format_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)