docstringify 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

docstringify/__init__.py

@@ -3,4 +3,4 @@ Flag missing docstrings and, optionally, generate them from signatures and
 type annotations.
 """
 
-__version__ = '0.2.0'
+__version__ = '0.3.0'

docstringify/cli.py

@@ -2,14 +2,22 @@ from __future__ import annotations
 
 import argparse
 import sys
+from functools import partial
 from typing import Sequence
 
 from . import __version__
 from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
+from .transformer import DocstringTransformer
 from .visitor import DocstringVisitor
 
 PROG = __package__
 
+STYLES = {
+    'google': GoogleDocstringConverter,
+    'numpydoc': NumpydocDocstringConverter,
+}
+CLI_DEFAULTS = {'threshold': 1.0}
+
 
 def main(argv: Sequence[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog=PROG)
@@ -22,45 +30,60 @@ def main(argv: Sequence[str] | None = None) -> int:
         '--version', action='version', version=f'%(prog)s {__version__}'
     )
 
-    parser.add_argument(
+    run_group = parser.add_argument_group('Run options')
+    handle_missing_docstring = run_group.add_mutually_exclusive_group(required=False)
+    handle_missing_docstring.add_argument(
+        '--make-changes',
+        choices=STYLES.keys(),
+        help='Whether to insert docstring templates for items missing docstrings',
+    )
+    handle_missing_docstring.add_argument(
+        '--make-changes-inplace',
+        choices=STYLES.keys(),
+        help=(
+            'Whether to insert docstring templates for items missing docstrings, '
+            'overwriting the original file'
+        ),
+    )
+    handle_missing_docstring.add_argument(
         '--suggest-changes',
-        action='store_true',
+        choices=STYLES.keys(),
         help='Whether to print out docstring templates for items missing docstrings',
     )
-    parser.add_argument(
-        '--style',
-        choices=['google', 'numpydoc'],
-        default='numpydoc',
-        help='The style of docstring to use (only used when --suggest-changes is passed)',
-    )
-    parser.add_argument(
+    run_group.add_argument(
         '--threshold',
         type=float,
-        default=1,
+        default=CLI_DEFAULTS['threshold'],
         help='The percentage of docstrings that must be present to pass',
     )
     args = parser.parse_args(argv)
 
-    if args.style is None or not args.suggest_changes:
-        converter = None
-    elif args.style == 'google':
-        converter = GoogleDocstringConverter()
-    elif args.style == 'numpydoc':
-        converter = NumpydocDocstringConverter()
+    if style := args.make_changes or args.make_changes_inplace or args.suggest_changes:
+        converter = STYLES[style]
     else:
-        raise NotImplementedError(f'{args.style} is not a supported option')
+        converter = None
+
+    get_docstring_processor = (
+        partial(
+            DocstringTransformer,
+            converter=converter,
+            **{'overwrite': bool(args.make_changes_inplace)},
+        )
+        if args.make_changes or args.make_changes_inplace
+        else partial(DocstringVisitor, converter=converter)
+    )
 
     docstrings_processed = missing_docstrings = 0
     for file in args.filenames:
-        visitor = DocstringVisitor(file, converter=converter)
-        visitor.process_file()
-        missing_docstrings += visitor.missing_docstrings
-        docstrings_processed += visitor.docstrings_inspected
+        processor = get_docstring_processor(file)
+        processor.process_file()
+        missing_docstrings += processor.missing_docstrings
+        docstrings_processed += processor.docstrings_inspected
 
     if docstrings_processed and (
         missing_percentage := (missing_docstrings / docstrings_processed)
     ) > (1 - args.threshold):
-        print(f'Missing {missing_percentage:.0%} of docstrings', file=sys.stderr)
+        print(f'\nMissing {missing_percentage:.0%} of docstrings', file=sys.stderr)
         print(
             f'Your settings require {args.threshold:.0%} of docstrings to be present',
             file=sys.stderr,

docstringify/converters/base.py

@@ -2,26 +2,33 @@
 
 from __future__ import annotations
 
+import textwrap
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
+from ..exceptions import InvalidDocstringError
+
 if TYPE_CHECKING:
     from ..components import Function, Parameter
 
 
 class DocstringConverter(ABC):
     def __init__(
-        self, parameters_section_template: str, returns_section_template: str
+        self,
+        parameters_section_template: str,
+        returns_section_template: str,
+        quote: bool,
     ) -> None:
         self.parameters_section_template = parameters_section_template
         self.returns_section_template = returns_section_template
+        self._quote = quote
 
     @abstractmethod
-    def to_class_docstring(self, class_name: str) -> str:
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_function_docstring(self, function: Function) -> str:
+    def to_function_docstring(self, function: Function, indent: int) -> str:
         pass
 
     @abstractmethod
@@ -49,3 +56,18 @@ class DocstringConverter(ABC):
         if return_text := self.format_return(return_type):
             return self.returns_section_template.format(returns=return_text)
         return ''
+
+    def quote_docstring(self, docstring: str | list[str], indent: int) -> str:
+        quote = '"""' if self._quote else ''
+        prefix = sep = ''
+        if isinstance(docstring, str):
+            docstring = [quote, docstring, quote]
+        elif isinstance(docstring, list):
+            if len(docstring) > 1:
+                prefix = ' ' * indent if indent else ''
+                sep = '\n'
+            docstring = [quote, *docstring, f'{prefix}{quote}']
+        else:
+            raise InvalidDocstringError(type(docstring).__name__)
+
+        return textwrap.indent(sep.join(docstring), prefix)

docstringify/converters/google.py

@@ -7,15 +7,15 @@ from .base import DocstringConverter
 
 
 class GoogleDocstringConverter(DocstringConverter):
-    def __init__(self) -> None:
+    def __init__(self, quote: bool) -> None:
         super().__init__(
             parameters_section_template='Args:\n{parameters}',
             returns_section_template='Returns:\n    {returns}',
+            quote=quote,
         )
 
-    def to_function_docstring(self, function: Function) -> str:
-        # TODO: the visitor needs the triple quotes but the transformer does not
-        docstring = [f'"""{DESCRIPTION_PLACEHOLDER}']
+    def to_function_docstring(self, function: Function, indent: int) -> str:
+        docstring = [DESCRIPTION_PLACEHOLDER]
 
         if parameters_section := self.parameters_section(function.parameters):
             docstring.extend(['', parameters_section])
@@ -23,14 +23,12 @@ class GoogleDocstringConverter(DocstringConverter):
         if returns_section := self.returns_section(function.return_type):
             docstring.extend(['', returns_section])
 
-        sep = '' if len(docstring) == 1 else '\n'
-
-        return sep.join([*docstring, '"""'])
+        return self.quote_docstring(docstring, indent=indent)
 
     def format_parameter(self, parameter: Parameter) -> str:
         category = f'{f", {parameter.category}" if parameter.category else ""}'
         return (
-            f'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER} '
+            f'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER}'
             f'{f" Defaults to {parameter.default}." if parameter.default != NO_DEFAULT else ""}'
         )
 
@@ -40,7 +38,7 @@ class GoogleDocstringConverter(DocstringConverter):
         return ''
 
     def to_module_docstring(self, module_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
 
-    def to_class_docstring(self, class_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

docstringify/converters/numpydoc.py

@@ -7,15 +7,15 @@ from .base import DocstringConverter
 
 
 class NumpydocDocstringConverter(DocstringConverter):
-    def __init__(self) -> None:
+    def __init__(self, quote: bool) -> None:
         super().__init__(
             parameters_section_template='Parameters\n----------\n{parameters}',
             returns_section_template='Returns\n-------\n{returns}',
+            quote=quote,
         )
 
-    def to_function_docstring(self, function: Function) -> str:
-        # TODO: the visitor needs the triple quotes but the transformer does not
-        docstring = ['"""', DESCRIPTION_PLACEHOLDER]
+    def to_function_docstring(self, function: Function, indent: int) -> str:
+        docstring = [DESCRIPTION_PLACEHOLDER]
 
         if parameters_section := self.parameters_section(function.parameters):
             docstring.extend(['', parameters_section])
@@ -23,9 +23,7 @@ class NumpydocDocstringConverter(DocstringConverter):
         if returns_section := self.returns_section(function.return_type):
             docstring.extend(['', returns_section])
 
-        sep = '' if len(docstring) == 2 else '\n'
-
-        return sep.join([*docstring, '"""'])
+        return self.quote_docstring(docstring, indent=indent)
 
     def format_parameter(self, parameter: Parameter) -> str:
         return (
@@ -41,7 +39,7 @@ class NumpydocDocstringConverter(DocstringConverter):
         return ''
 
     def to_module_docstring(self, module_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
 
-    def to_class_docstring(self, class_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

docstringify/docstring_generator.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, Literal
+
+from .components import (
+    NO_DEFAULT,
+    PARAMETER_TYPE_PLACEHOLDER,
+    RETURN_TYPE_PLACEHOLDER,
+    Function,
+    Parameter,
+)
+
+if TYPE_CHECKING:
+    from .converters import DocstringConverter
+
+
+class DocstringGenerator:
+    def __init__(
+        self,
+        converter: type[DocstringConverter],
+        module_name: str,
+        source_code: str,
+        quote: bool,
+    ) -> None:
+        self.converter = converter(quote=quote)
+        self.module_name = module_name
+        self.source_code = source_code
+
+    def _extract_default_values(
+        self, default: ast.Constant | None | Literal[NO_DEFAULT], is_keyword_only: bool
+    ) -> str | Literal[NO_DEFAULT]:
+        if (not is_keyword_only and default is not NO_DEFAULT) or (
+            is_keyword_only and default
+        ):
+            try:
+                default_value = default.value
+            except AttributeError:
+                default_value = f'`{default.id}`'
+
+            return (
+                f'"{default_value}"'
+                if isinstance(default_value, str) and not default_value.startswith('`')
+                else default_value
+            )
+        return NO_DEFAULT
+
+    def extract_arguments(
+        self, node: ast.AsyncFunctionDef | ast.FunctionDef
+    ) -> tuple[Parameter, ...]:
+        modifiers = {
+            'posonlyargs': 'positional-only',
+            'kwonlyargs': 'keyword-only',
+        }
+        params = []
+
+        positional_arguments_count = len(node.args.posonlyargs) + len(node.args.args)
+        if (
+            default_count := len(positional_defaults := node.args.defaults)
+        ) < positional_arguments_count:
+            positional_defaults = [NO_DEFAULT] * (
+                positional_arguments_count - default_count
+            ) + positional_defaults
+
+        keyword_defaults = node.args.kw_defaults
+
+        processed_positional_args = 0
+        for arg_type, args in ast.iter_fields(node.args):
+            if arg_type.endswith('defaults'):
+                continue
+            modifier = modifiers.get(arg_type)
+            if arg_type in ['vararg', 'kwarg']:
+                if args:
+                    params.append(
+                        Parameter(
+                            name=f'*{args.arg}'
+                            if arg_type == 'vararg'
+                            else f'**{args.arg}',
+                            type_=getattr(
+                                args.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
+                            ),
+                            category=modifier,
+                            default=NO_DEFAULT,
+                        )
+                    )
+            else:
+                is_keyword_only = arg_type.startswith('kw')
+                params.extend(
+                    [
+                        Parameter(
+                            name=arg.arg,
+                            type_=getattr(
+                                arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
+                            ),
+                            category=modifier,
+                            default=self._extract_default_values(
+                                default, is_keyword_only
+                            ),
+                        )
+                        for arg, default in zip(
+                            args,
+                            keyword_defaults
+                            if is_keyword_only
+                            else positional_defaults[processed_positional_args:],
+                        )
+                    ]
+                )
+                if not is_keyword_only:
+                    processed_positional_args += len(args)
+
+        params = tuple(params)
+        if (
+            params
+            and isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
+            and params[0].name.startswith(('self', 'cls'))
+        ):
+            return params[1:]
+        return params
+
+    def extract_returns(
+        self, node: ast.AsyncFunctionDef | ast.FunctionDef
+    ) -> str | None:
+        if return_node := node.returns:
+            if isinstance(return_node, ast.Constant):
+                return return_node.value
+            if isinstance(return_node, ast.Name):
+                return return_node.id
+            return ast.get_source_segment(self.source_code, return_node)
+        if (
+            return_nodes := [
+                body_node
+                for body_node in node.body
+                if isinstance(body_node, ast.Return)
+            ]
+        ) and any(
+            not isinstance(return_value := body_return_node.value, ast.Constant)
+            or return_value.value
+            for body_return_node in return_nodes
+        ):
+            return RETURN_TYPE_PLACEHOLDER
+        return return_node
+
+    def suggest_docstring(
+        self,
+        node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module,
+        indent: int = 0,
+    ) -> str:
+        if isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef):
+            return self.converter.to_function_docstring(
+                Function(self.extract_arguments(node), self.extract_returns(node)),
+                indent=indent,
+            )
+
+        if isinstance(node, ast.Module):
+            return self.converter.to_module_docstring(self.module_name)
+
+        return self.converter.to_class_docstring(node.name, indent=indent)

docstringify/exceptions.py

@@ -0,0 +1,6 @@
+"""Docstringify exceptions."""
+
+
+class InvalidDocstringError(ValueError):
+    def __init__(self, docstring_class: str) -> None:
+        super().__init__(f'Expected str or list[str] docstring, got {docstring_class}')

docstringify/transformer.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+from .visitor import DocstringVisitor
+
+if TYPE_CHECKING:
+    from .converters import DocstringConverter
+
+
+class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
+    def __init__(
+        self, filename: str, converter: DocstringConverter, overwrite: bool = False
+    ) -> None:
+        super().__init__(filename, converter)
+        self.overwrite = overwrite
+
+    def save(self, new_ast: ast.Module) -> None:
+        if self.missing_docstrings:
+            output = (
+                self.source_file
+                if self.overwrite
+                else self.source_file.parent
+                / (
+                    self.source_file.stem
+                    + '_docstringify'
+                    + ''.join(self.source_file.suffixes)
+                )
+            )
+            edited_code = ast.unparse(new_ast)
+            output.write_text(edited_code)
+            print(f'Docstring templates written to {output}')
+        else:
+            print(
+                f'No missing docstrings found in {self.source_file}; no changes made.'
+            )
+
+    def handle_missing_docstring(
+        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
+    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
+        suggested_docstring = self.docstring_generator.suggest_docstring(
+            node, indent=0 if isinstance(node, ast.Module) else node.col_offset + 4
+        )
+        docstring = ast.Expr(ast.Constant(suggested_docstring))
+        node.body.insert(0, docstring)
+        return ast.fix_missing_locations(node)
+
+    def process_file(self) -> ast.Module:
+        root = ast.parse(self.source_code)
+        new_ast = self.visit(root)
+        self.save(new_ast)
+        return new_ast

docstringify/visitor.py

@@ -3,15 +3,9 @@ from __future__ import annotations
 import ast
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING
 
-from .components import (
-    NO_DEFAULT,
-    PARAMETER_TYPE_PLACEHOLDER,
-    RETURN_TYPE_PLACEHOLDER,
-    Function,
-    Parameter,
-)
+from .docstring_generator import DocstringGenerator
 
 if TYPE_CHECKING:
     from .converters import DocstringConverter
@@ -21,7 +15,7 @@ class DocstringVisitor(ast.NodeVisitor):
     def __init__(
         self, filename: str, converter: DocstringConverter | None = None
     ) -> None:
-        self.source_file: Path = Path(filename)
+        self.source_file: Path = Path(filename).expanduser().resolve()
         self.source_code: str = self.source_file.read_text()
 
         self.docstrings_inspected: int = 0
@@ -32,154 +26,37 @@ class DocstringVisitor(ast.NodeVisitor):
 
         self.provide_hints: bool = converter is not None
         if self.provide_hints:
-            self.converter: DocstringVisitor = converter  # TODO: consider whether this should be instantiated here instead of outside
-
-    def _extract_default_values(
-        self, default: ast.Constant | None | Literal[NO_DEFAULT], is_keyword_only: bool
-    ) -> str | Literal[NO_DEFAULT]:
-        if (not is_keyword_only and default is not NO_DEFAULT) or (
-            is_keyword_only and default
-        ):
-            try:
-                default_value = default.value
-            except AttributeError:
-                default_value = f'`{default.id}`'
-
-            return (
-                f'"{default_value}"'
-                if isinstance(default_value, str) and not default_value.startswith('`')
-                else default_value
+            self.docstring_generator = DocstringGenerator(
+                converter,
+                self.module_name,
+                self.source_code,
+                quote=not issubclass(self.__class__, ast.NodeTransformer),
             )
-        return NO_DEFAULT
-
-    def extract_arguments(
-        self, node: ast.AsyncFunctionDef | ast.FunctionDef
-    ) -> tuple[Parameter, ...]:
-        modifiers = {
-            'posonlyargs': 'positional-only',
-            'kwonlyargs': 'keyword-only',
-        }
-        params = []
-
-        positional_arguments_count = len(node.args.posonlyargs) + len(node.args.args)
-        if (
-            default_count := len(positional_defaults := node.args.defaults)
-        ) < positional_arguments_count:
-            positional_defaults = [NO_DEFAULT] * (
-                positional_arguments_count - default_count
-            ) + positional_defaults
-
-        keyword_defaults = node.args.kw_defaults
-
-        processed_positional_args = 0
-        for arg_type, args in ast.iter_fields(node.args):
-            if arg_type.endswith('defaults'):
-                continue
-            modifier = modifiers.get(arg_type)
-            if arg_type in ['vararg', 'kwarg']:
-                if args:
-                    params.append(
-                        Parameter(
-                            name=f'*{args.arg}'
-                            if arg_type == 'vararg'
-                            else f'**{args.arg}',
-                            type_=getattr(
-                                args.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
-                            ),
-                            category=modifier,
-                            default=NO_DEFAULT,
-                        )
-                    )
-            else:
-                is_keyword_only = arg_type.startswith('kw')
-                params.extend(
-                    [
-                        Parameter(
-                            name=arg.arg,
-                            type_=getattr(
-                                arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
-                            ),
-                            category=modifier,
-                            default=self._extract_default_values(
-                                default, is_keyword_only
-                            ),
-                        )
-                        for arg, default in zip(
-                            args,
-                            keyword_defaults
-                            if is_keyword_only
-                            else positional_defaults[processed_positional_args:],
-                        )
-                    ]
-                )
-                if not is_keyword_only:
-                    processed_positional_args += len(args)
-
-        params = tuple(params)
-        if (
-            params
-            and isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
-            and params[0].name.startswith(('self', 'cls'))
-        ):
-            return params[1:]
-        return params
-
-    def extract_returns(
-        self, node: ast.AsyncFunctionDef | ast.FunctionDef
-    ) -> str | None:
-        if return_node := node.returns:
-            if isinstance(return_node, ast.Constant):
-                return return_node.value
-            if isinstance(return_node, ast.Name):
-                return return_node.id
-            return ast.get_source_segment(self.source_code, return_node)
-        if (
-            return_nodes := [
-                body_node
-                for body_node in node.body
-                if isinstance(body_node, ast.Return)
-            ]
-        ) and any(
-            not isinstance(return_value := body_return_node.value, ast.Constant)
-            or return_value.value
-            for body_return_node in return_nodes
-        ):
-            return RETURN_TYPE_PLACEHOLDER
-        return return_node
 
     def report_missing_docstring(self) -> None:
         self.missing_docstrings += 1
         print(f'{".".join(self.stack)} is missing a docstring', file=sys.stderr)
 
-    def suggest_docstring(
+    def handle_missing_docstring(
         self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> str:
-        if isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef):
-            return self.converter.to_function_docstring(
-                Function(self.extract_arguments(node), self.extract_returns(node))
-            )
-
-        if isinstance(node, ast.Module):
-            return self.converter.to_module_docstring(self.module_name)
-
-        # TODO: with the stack, I should be able to let __init__() not have a docstring
-        # and suggest those parameters as the docstring for the class
-        # (may need to keep the class node in another stack)
-        return self.converter.to_class_docstring(node.name)
+    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
+        if self.provide_hints:
+            print('Hint:')
+            print(self.docstring_generator.suggest_docstring(node))
+            print()
+        return node
 
     def process_docstring(
         self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> None:
+    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
         if not ast.get_docstring(node):
             self.report_missing_docstring()
-            if self.provide_hints:
-                print('Hint:')
-                print(self.suggest_docstring(node))
-                print()
+            node = self.handle_missing_docstring(node)
 
         self.docstrings_inspected += 1
+        return node
 
-    def visit(self, node: ast.AST) -> None:
+    def visit(self, node: ast.AST) -> ast.AST:
         if isinstance(
             node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
         ):
@@ -187,10 +64,16 @@ class DocstringVisitor(ast.NodeVisitor):
                 self.module_name if isinstance(node, ast.Module) else node.name
             )
 
-            self.process_docstring(node)
+            node = self.process_docstring(node)
 
             self.generic_visit(node)
             _ = self.stack.pop()
+        return node
+
+    def process_file(self) -> ast.Module:
+        root = self.visit(ast.parse(self.source_code))
+
+        if not self.missing_docstrings:
+            print(f'No missing docstrings found in {self.source_file}.')
 
-    def process_file(self) -> None:
-        self.visit(ast.parse(self.source_code))
+        return root

{docstringify-0.2.0.dist-info → docstringify-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.2.0
+Version: 0.3.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -60,7 +60,7 @@ Add the following to your `.pre-commit-config.yaml` file to block commits with m
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.3.0
   hooks:
     - id: docstringify
 ```
@@ -69,32 +69,34 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.3.0
   hooks:
     - id: docstringify
       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. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#):
+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:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.3.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
-For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.3.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes, --style=google]
+      args: [--make-changes=google]
 ```
 
+If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` &ndash; make sure you only operate on files that are in version control with this setting. Note that the resulting format of your file may be a little different (spacing, newlines, *etc.*).
+
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
 ### Command line
@@ -136,8 +138,8 @@ If you would like to see suggested docstring templates (inferred from type annot
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
 >>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
->>> visitor.process_file()
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
+>>> _ = visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -154,3 +156,17 @@ name : str, default="World"
 """
 
 ```
+
+To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.transformer import DocstringTransformer
+>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
+>>> _ = transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test_docstringify.py
+```
+
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.

docstringify-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+docstringify/__init__.py,sha256=lJ-zemDc-oz26qgkRmOW06LIk6B28i8dKizCqJVlpFc,124
+docstringify/__main__.py,sha256=A5Xq9jCZwHnQVVGklF9ueL-ad-hInsceHQNgze3Yq6E,96
+docstringify/cli.py,sha256=lRBSIEsFLnYYkheKaq7lxu5Kb8zdG9u7FvTA-YpJ7B0,3010
+docstringify/components.py,sha256=7Q__cuBTWNAqLDTil_91Q7T-zIzr7YpbX2TcmXrfph0,471
+docstringify/docstring_generator.py,sha256=v0N9ge_TAwCCGwjO9o2ka9Wux6yIezXn8NUW5EJNlyI,5458
+docstringify/exceptions.py,sha256=lt9p6bUGGqwsKCBk0hv4LrMqOLzNuk-E_3rXgjVKGpc,216
+docstringify/transformer.py,sha256=adU_eY2HspNXAabn8BH_itp0i4x5wKmhQoH02qzbGe4,1836
+docstringify/visitor.py,sha256=W7Zexf4D2Wt3thlDA-e1cWPhlhcaazYkSkp_zbbrotg,2610
+docstringify/converters/__init__.py,sha256=iZXA6m689j3yqpfZjkoAcONXxAR7s-4GUQFEYxDPAyc,267
+docstringify/converters/base.py,sha256=K_oAmVhWl8L6igFxJRluyn9DuZNtJi5UltyBTaTHc90,2268
+docstringify/converters/google.py,sha256=puOCpmCK4InimfjR8TAcvCT_ZdpF_U0z_4E8a5l1UWk,1738
+docstringify/converters/numpydoc.py,sha256=VDQGvknBJMP9o6D9wh3cKsL7-uGNuDP4Ow7C3-Tf08c,1762
+docstringify-0.3.0.dist-info/licenses/LICENSE,sha256=E5RHv_qfCZPwnlJ_ZQb-WKOOy07LaJBA2a160OGtT3U,1071
+docstringify-0.3.0.dist-info/METADATA,sha256=h1yDuJB7d8QoAc82aY9u6iHdSyVFBafsS0CxhhUkZM8,6454
+docstringify-0.3.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+docstringify-0.3.0.dist-info/entry_points.txt,sha256=dJVPsbclB7stLE8g0d4WbO2NaZQLJXSLEVl6oeROAqI,55
+docstringify-0.3.0.dist-info/top_level.txt,sha256=3RFmaFG0rYs4HkqRljatGQtY4BcNN7mqjK4tSznYdnQ,13
+docstringify-0.3.0.dist-info/RECORD,,

docstringify-0.2.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-docstringify/__init__.py,sha256=F8wAs3yjndnNfOVnCZIiCk86BQIwxiAGx7fXe15mxNE,124
-docstringify/__main__.py,sha256=A5Xq9jCZwHnQVVGklF9ueL-ad-hInsceHQNgze3Yq6E,96
-docstringify/cli.py,sha256=U2G97RihJC2HMR2MCWDNadcU5erBuFDlIDrIOQ4lJSM,2230
-docstringify/components.py,sha256=7Q__cuBTWNAqLDTil_91Q7T-zIzr7YpbX2TcmXrfph0,471
-docstringify/visitor.py,sha256=qF6T6lqbK93RArbkDhqZYOQNAuvi6miMehO0U9tdNJM,7019
-docstringify/converters/__init__.py,sha256=iZXA6m689j3yqpfZjkoAcONXxAR7s-4GUQFEYxDPAyc,267
-docstringify/converters/base.py,sha256=1QWFE5ckS_Rbwi9TyRM-rKCA7MCwHgZ4Ok8ugMyvMgA,1507
-docstringify/converters/google.py,sha256=ytel_pqqUNV5wR8nVV1F8yczFA3Tj1f9_nkfJA4Kq04,1751
-docstringify/converters/numpydoc.py,sha256=iv5smFrHFBc0rHvLhgh66PaV2OEI3va_piRZ3_y2Ig8,1773
-docstringify-0.2.0.dist-info/licenses/LICENSE,sha256=E5RHv_qfCZPwnlJ_ZQb-WKOOy07LaJBA2a160OGtT3U,1071
-docstringify-0.2.0.dist-info/METADATA,sha256=QvPrAwX5TnbG6y7XpK6grHqohENJ2doN3i0WiHipECk,5362
-docstringify-0.2.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-docstringify-0.2.0.dist-info/entry_points.txt,sha256=dJVPsbclB7stLE8g0d4WbO2NaZQLJXSLEVl6oeROAqI,55
-docstringify-0.2.0.dist-info/top_level.txt,sha256=3RFmaFG0rYs4HkqRljatGQtY4BcNN7mqjK4tSznYdnQ,13
-docstringify-0.2.0.dist-info/RECORD,,