Update pydoclint config and fix docstrings (#155)

* Update pydoclint config and fix docstrings

* Remove uneeded ignore

Author: cidrblock

pyproject.toml

@@ -67,6 +67,8 @@ strict = true
 allow-init-docstring = true
 arg-type-hints-in-docstring = false
 check-return-types = false
+show-filenames-in-every-violation-message = true
+skip-checking-short-docstrings = false
 style = 'google'
 
 [tool.pylint]

src/ansible_dev_environment/arg_parser.py

@@ -6,8 +6,12 @@
 
 from argparse import HelpFormatter
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 
+if TYPE_CHECKING:
+    from typing import Any
+
 try:
     from ._version import version as __version__  # type: ignore[unused-ignore,import-not-found]
 except ImportError:  # pragma: no cover
@@ -214,12 +218,17 @@ def parse() -> argparse.Namespace:
 class ArgumentParser(argparse.ArgumentParser):
     """A custom argument parser."""
 
-    def add_argument(  # type: ignore[no-untyped-def, override]
+    def add_argument(  # type: ignore[override]
         self: ArgumentParser,
-        *args,  # noqa: ANN002
-        **kwargs,  # noqa: ANN003
+        *args: Any,  # noqa: ANN401
+        **kwargs: Any,  # noqa: ANN401
     ) -> None:
-        """Add an argument."""
+        """Add an argument.
+
+        Args:
+            *args: The arguments
+            **kwargs: The keyword arguments
+        """
         if "choices" in kwargs:
             kwargs["help"] += f" (choices: {', '.join(kwargs['choices'])})"
         if "default" in kwargs and kwargs["default"] != "==SUPPRESS==":
@@ -234,7 +243,8 @@ class CustomHelpFormatter(HelpFormatter):
     def __init__(self: CustomHelpFormatter, prog: str) -> None:
         """Initialize the help formatter.
 
-        :param prog: The program name
+        Args:
+            prog: The program name
         """
         long_string = "--abc  --really_really_really_log"
         # 3 here accounts for the spaces in the ljust(6) below

src/ansible_dev_environment/collection.py

@@ -54,7 +54,13 @@ def build_dir(self: Collection) -> Path:
 
     @property
     def site_pkg_path(self: Collection) -> Path:
-        """Return the site packages collection path."""
+        """Return the site packages collection path.
+
+        Returns:
+            The site packages collection path
+        Raises:
+            RuntimeError: If the collection namespace or name is not set
+        """
         if not self.cnamespace or not self.cname:
             msg = "Collection namespace or name not set."
             raise RuntimeError(msg)

src/ansible_dev_environment/config.py

@@ -31,7 +31,13 @@ def __init__(
         output: Output,
         term_features: TermFeatures,
     ) -> None:
-        """Initialize the configuration."""
+        """Initialize the configuration.
+
+        Args:
+            args: The command line arguments
+            output: The output object
+            term_features: The terminal features
+        """
         self._create_venv: bool = False
         self.args: Namespace = args
         self.bindir: Path

src/ansible_dev_environment/output.py

@@ -30,8 +30,10 @@ def round_half_up(number: float) -> int:
 
     This will always round based on distance from zero. (e.g round(2.5) = 3, round(3.5) = 4).
 
-    :param number: The number to round
-    :returns: The rounded number as an it
+    Args:
+        number: The number to round
+    Returns:
+        The rounded number as an it
     """
     rounded = decimal.Decimal(number).quantize(
         decimal.Decimal("1"),
@@ -43,7 +45,8 @@ def round_half_up(number: float) -> int:
 def console_width() -> int:
     """Get a console width based on common screen widths.
 
-    :returns: The console width
+    Returns:
+        The console width
     """
     medium = 80
     wide = 132
@@ -109,22 +112,25 @@ def log_level(self: Level) -> int:
     def _longest_name(cls: type[T]) -> int:
         """Return the longest exit message prefix.
 
-        :returns: The longest exit message prefix
+        Returns:
+            The longest exit message prefix
         """
         return max(len(member.value) for member in cls)
 
     @classmethod
     def longest_formatted(cls: type[T]) -> int:
         """Return the longest exit message prefix.
 
-        :returns: The longest exit message prefix
+        Returns:
+            The longest exit message prefix
         """
         return max(len(str(member)) for member in cls)
 
     def __str__(self: Level) -> str:
         """Return the exit message prefix as a string.
 
-        :returns: The exit message prefix as a string
+        Returns:
+            The exit message prefix as a string
         """
         return (
             f"{' ' * (self._longest_name() - len(self.name))}{self.name.capitalize()}: "
@@ -165,10 +171,12 @@ def to_lines(
     ) -> list[str]:
         """Output exit message to the console.
 
-        :param color: Whether to color the message
-        :param width: Constrain message to width
-        :param with_prefix: Whether to prefix the message
-        :returns: The exit message as a string
+        Args:
+            color: Whether to color the message
+            width: Constrain message to width
+            with_prefix: Whether to prefix the message
+        Returns:
+            The exit message as a string
         """
         prefix_length = Level.longest_formatted()
         indent = " " * prefix_length
@@ -256,7 +264,8 @@ def __init__(  # noqa: PLR0913
     def critical(self: Output, msg: str) -> None:
         """Print a critical message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["critical"] += 1
         self.log(msg, level=Level.CRITICAL)
@@ -265,56 +274,63 @@ def critical(self: Output, msg: str) -> None:
     def debug(self: Output, msg: str) -> None:
         """Print a debug message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["debug"] += 1
         self.log(msg, level=Level.DEBUG)
 
     def error(self: Output, msg: str) -> None:
         """Print an error message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["error"] += 1
         self.log(msg, level=Level.ERROR)
 
     def hint(self: Output, msg: str) -> None:
         """Print a hint message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["hint"] += 1
         self.log(msg, level=Level.HINT)
 
     def info(self: Output, msg: str) -> None:
         """Print a hint message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["info"] += 1
         self.log(msg, level=Level.INFO)
 
     def note(self: Output, msg: str) -> None:
         """Print a note message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["note"] += 1
         self.log(msg, level=Level.NOTE)
 
     def warning(self: Output, msg: str) -> None:
         """Print a warning message to the console.
 
-        :param msg: The message to print
+        Args:
+            msg: The message to print
         """
         self.call_count["warning"] += 1
         self.log(msg, level=Level.WARNING)
 
     def log(self: Output, msg: str, level: Level = Level.ERROR) -> None:
         """Print a message to the console.
 
-        :param msg: The message to print
-        :param prefix: The prefix for the message
+        Args:
+            msg: The message to print
+            level: The message level
         """
         if self.log_to_file:
             self.logger.log(level.log_level, msg, stacklevel=3)

src/ansible_dev_environment/subcommands/installer.py

@@ -146,7 +146,11 @@ def _install_galaxy_collections(
         self: Installer,
         collections: list[Collection],
     ) -> None:
-        """Install the collection from galaxy."""
+        """Install the collection from galaxy.
+
+        Args:
+            collections: The collection objects.
+        """
         collections_str = " ".join(
             [f"'{collection.original}'" for collection in collections],
         )

src/ansible_dev_environment/subcommands/lister.py

@@ -26,7 +26,11 @@ def __init__(self: Lister, config: Config, output: Output) -> None:
         self._output = output
 
     def run(self: Lister) -> None:
-        """Run the Lister."""
+        """Run the Lister.
+
+        Raises:
+            TypeError: If the link is not a string.
+        """
         # pylint: disable=too-many-locals
         collections = collect_manifests(
             target=self._config.site_pkg_collections_path,

src/ansible_dev_environment/subcommands/treemaker.py

@@ -30,7 +30,11 @@ def __init__(self: TreeMaker, config: Config, output: Output) -> None:
         self._output = output
 
     def run(self: TreeMaker) -> None:  # noqa: C901, PLR0912, PLR0915
-        """Run the command."""
+        """Run the command.
+
+        Raises:
+            TypeError: If the tree dict is not a dict.
+        """
         # pylint: disable=too-many-locals
         builder_introspect(self._config, self._output)
 

src/ansible_dev_environment/tree.py

@@ -23,7 +23,12 @@ def __init__(
         obj: JSONVal,
         term_features: TermFeatures,
     ) -> None:
-        """Initialize the renderer."""
+        """Initialize the renderer.
+
+        Args:
+            obj: The object to render
+            term_features: The terminal features
+        """
         self.obj = obj
         self._lines: list[str] = []
         self.blue: list[ScalarVal] = []
@@ -85,7 +90,13 @@ def in_color(self: Tree, val: ScalarVal) -> str:
 
     @staticmethod
     def is_scalar(obj: JSONVal) -> bool:
-        """Check if the object is a scalar."""
+        """Check if the object is a scalar.
+
+        Args:
+            obj: The object to check
+        Returns:
+            Whether the object is a scalar
+        """
         return isinstance(obj, str | int | float | bool) or obj is None
 
     def _print_tree(  # noqa: C901, PLR0913, PLR0912
@@ -167,11 +178,19 @@ def _print_tree(  # noqa: C901, PLR0913, PLR0912
             raise TypeError(err)
 
     def append(self: Tree, string: str) -> None:
-        """Append a line to the output."""
+        """Append a line to the output.
+
+        Args:
+            string: The string to append
+        """
         self._lines.append(string)
 
     def render(self: Tree) -> str:
-        """Render the root of the tree."""
+        """Render the root of the tree.
+
+        Returns:
+            The rendered tree
+        """
         # if not isinstance(self.obj, dict):
         self._print_tree(self.obj, is_last=False, is_root=True, was_list=False)
         return "\n".join(self._lines) + "\n"