Add darglint hook, and enable pydocstyle on ruff (#87)

Author: Qalthos

.darglint

@@ -0,0 +1,7 @@
+[darglint]
+# NOTE: All `darglint` styles except for `sphinx` hit ridiculously low
+# NOTE: performance on some of the in-project Python modules.
+# Refs:
+# * https://github.com/terrencepreilly/darglint/issues/186
+docstring_style = sphinx
+strictness = full

.pre-commit-config.yaml

@@ -22,3 +22,8 @@ repos:
       - id: end-of-file-fixer
       - id: no-commit-to-branch
       - id: trailing-whitespace
+
+  - repo: https://github.com/terrencepreilly/darglint
+    rev: v1.8.1
+    hooks:
+      - id: darglint

collection_prep/cmd/__init__.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python
 # PYTHON_ARGCOMPLETE_OK
 
-""" doc generator
-"""
+"""Generate or update collection documentation."""
 import ast
 import logging
 import os
@@ -71,7 +70,7 @@
 
 
 def ensure_list(value):
-    """Ensure the value is a list
+    """Ensure the value is a list.
 
     :param value: The value to check
     :type value: Unknown
@@ -83,7 +82,7 @@ def ensure_list(value):
 
 
 def convert_descriptions(data):
-    """Convert the descriptions for doc into lists
+    """Convert the descriptions for doc into lists.
 
     :param data: the chunk from the doc
     :type data: dict
@@ -99,7 +98,7 @@ def convert_descriptions(data):
 
 
 def jinja_environment():
-    """Define the jinja environment
+    """Define the jinja environment.
 
     :return: A jinja template, with the env set
     """
@@ -121,12 +120,10 @@ def jinja_environment():
 
 
 def update_readme(content, path, gh_url, branch_name):
-    """Update the README.md in the repository
+    """Update the README.md in the repository.
 
     :param content: The dict containing the content
     :type content: dict
-    :param collection: The full collection name
-    :type collection: str
     :param path: The path to the collection
     :type path: str
     :param gh_url: The url to the GitHub repository
@@ -193,9 +190,7 @@ def update_readme(content, path, gh_url, branch_name):
 
 
 def handle_simple(collection, fullpath, kind):
-    """Grab each plugin from a plugin file and
-    use the def comment if available. Intended for use
-    with "simple" plugins, like filter or tests
+    """Process "simple" plugins like filter or test.
 
     :param collection: The full collection name
     :type collection: str
@@ -276,9 +271,7 @@ def handle_simple(collection, fullpath, kind):
     simple_map = dict(zip(keys, values))
     for name, func in simple_map.items():
         if func in function_definitions:
-            comment = function_definitions[func] or "{collection} {name} {kind} plugin".format(
-                collection=collection, name=name, kind=kind
-            )
+            comment = function_definitions[func] or f"{collection} {name} {kind} plugin"
 
             # Get the first line from the docstring for the description and
             # make that the short description.
@@ -288,13 +281,13 @@ def handle_simple(collection, fullpath, kind):
 
 
 def process(collection: str, path: Path):  # pylint: disable-msg=too-many-locals
-    """
-    Process the files in each subdirectory
+    """Process the files in each subdirectory.
 
     :param collection: The collection name
     :type collection: str
     :param path: The path to the collection
-    :type path: str
+    :type path: Path
+    :return: A mapping of plugins to plugin types
     """
     template = jinja_environment()
     docs_path = Path(path, "docs")
@@ -377,7 +370,7 @@ def process(collection: str, path: Path):  # pylint: disable-msg=too-many-locals
 
 
 def load_galaxy(path):
-    """Load collection details from the galaxy.yml file in the collection
+    """Load collection details from the galaxy.yml file in the collection.
 
     :param path: The path the collection
     :return: The collection name and gh url
@@ -395,7 +388,7 @@ def load_galaxy(path):
 
 
 def load_runtime(path):
-    """Load runtime details from the runtime.yml file in the collection
+    """Load runtime details from the runtime.yml file in the collection.
 
     :param path: The path the collection
     :return: The runtime dict
@@ -413,14 +406,14 @@ def load_runtime(path):
 
 
 def link_collection(path: Path, galaxy: dict, collection_root: Optional[Path] = None):
-    """Link the provided collection into the Ansible default collection path
+    """Link the provided collection into the Ansible default collection path.
 
     :param path: A path
-    :type path: str
+    :type path: Path
     :param galaxy: The galaxy.yml contents
     :type galaxy: dict
+    :param collection_root: The root collections path
     """
-
     if collection_root is None:
         collection_root = Path(Path.home(), ".ansible/collections/ansible_collections")
 
@@ -448,7 +441,12 @@ def link_collection(path: Path, galaxy: dict, collection_root: Optional[Path] =
 
 
 def add_collection(path: Path, galaxy: dict) -> Optional[tempfile.TemporaryDirectory]:
-    """Add path to collections dir so we can find local doc_fragments"""
+    """Add path to collections dir so we can find local doc_fragments.
+
+    :param path: The collections path
+    :param galaxy: The contents of galaxy.yml
+    :return: A temporary alternate directory if the collection is not in a valid location
+    """
     collections_path = None
     tempdir = None
 
@@ -480,7 +478,7 @@ def add_collection(path: Path, galaxy: dict) -> Optional[tempfile.TemporaryDirec
 
 
 def add_ansible_compatibility(runtime, path):
-    """Add ansible compatibility information to README
+    """Add ansible compatibility information to README.
 
     :param runtime: runtime.yml contents
     :type runtime: dict
@@ -515,9 +513,7 @@ def add_ansible_compatibility(runtime, path):
 
 
 def main():
-    """
-    The entry point
-    """
+    """Run the script."""
     parser = ArgumentParser()
     parser.add_argument(
         "-p",

collection_prep/cmd/add_docs.py

@@ -1,6 +1,4 @@
-"""
-Get ready for 1.0.0
-"""
+"""Get ready for 1.0.0."""
 import glob
 import logging
 import os
@@ -23,12 +21,21 @@
 REMOVAL_DAY_OF_MONTH = "01"
 
 
-def get_warning_msg(plugin_name=None):
-    depcrecation_msg = "See the plugin documentation for more details"
-    return depcrecation_msg
+def get_warning_msg():
+    """Return warning text for a plugin.
+
+    :return: Additional details on the deprecation
+    """
+    return "See the plugin documentation for more details"
 
 
 def process_runtime_plugin_routing(collection, path):
+    """Process collection plugins to generate a plugin routing map.
+
+    :param collection: The name of the collection
+    :param path: The collections path
+    :return: A dictionary representing plugins and redirects and deprecations
+    """
     plugin_routing = {}
     plugins_path = f"{path}/{collection}/plugins"
     modules_path = f"{plugins_path}/modules"
@@ -93,7 +100,7 @@ def process_runtime_plugin_routing(collection, path):
                     module_name: {
                         "deprecation": {
                             "removal_date": get_removed_at_date(),
-                            "warning_text": get_warning_msg(f"{collection}.{module_name}"),
+                            "warning_text": get_warning_msg(),
                         }
                     }
                 }
@@ -106,7 +113,7 @@ def process_runtime_plugin_routing(collection, path):
                     {
                         "deprecation": {
                             "removal_date": get_removed_at_date(),
-                            "warning_text": get_warning_msg(f"{collection}.{short_name}"),
+                            "warning_text": get_warning_msg(),
                         }
                     }
                 )
@@ -115,6 +122,11 @@ def process_runtime_plugin_routing(collection, path):
 
 
 def process(collection, path):
+    """Generate or update runtime.yml on a collection.
+
+    :param collection: The collection name
+    :param path: The collections path
+    """
     rt_obj = {}
     collection_path = os.path.join(path, collection)
     if not os.path.exists(collection_path):
@@ -143,9 +155,7 @@ def process(collection, path):
 
 
 def main():
-    """
-    The entry point
-    """
+    """Run the script."""
     parser = ArgumentParser()
     parser.add_argument("-c", "--collection", help="The name of the collection", required=True)
     parser.add_argument("-p", "--path", help="The path to the collection", required=True)

collection_prep/cmd/runtime.py

@@ -1,6 +1,4 @@
-"""
-Get ready for 1.0.0
-"""
+"""Get ready for 1.0.0."""
 import logging
 import os
 import platform
@@ -35,8 +33,7 @@
 
 
 def remove_assigment_in_ast(name, ast_file):
-    """
-    REmoves an assignment in an ast object
+    """Remove an assignment in an ast object.
 
     :param name: The name of the assignement to remove
     :param ast_file: The ast object
@@ -47,9 +44,9 @@ def remove_assigment_in_ast(name, ast_file):
 
 
 def retrieve_plugin_name(plugin_type, bodypart):
-    """
-    Retrieve the module name from a docstring
+    """Retrieve the module name from a docstring.
 
+    :param plugin_type: The plugin's type
     :param bodypart: The doctstring extracted from the ast body
     :return: The module name
     """
@@ -65,15 +62,18 @@ def retrieve_plugin_name(plugin_type, bodypart):
 
 
 def update_deprecation_notice(documentation):
+    """Update deprecation notices to use removed_at_date instead of removed_in.
+
+    :param documentation: The DOCUMENTATION section of the module
+    """
     if "deprecated" in documentation:
         logging.info("Updating deprecation notice")
         documentation["deprecated"].update({"removed_at_date": get_removed_at_date()})
         documentation["deprecated"].pop("removed_in", None)
 
 
 def update_documentation(bodypart):
-    """
-    Update the docuementation of the module
+    """Update the documentation of the module.
 
     :param bodypart: The DOCUMENTATION section of the module
     """
@@ -100,14 +100,12 @@ def update_documentation(bodypart):
 
 
 def update_examples(bodypart, module_name, collection):
-    """
-    Update the example
+    """Update the example.
 
     :param bodypart: The EXAMPLE section of the module
     :param module_name: The name of the module
     :param collection: The name of the collection
     """
-
     if not bodypart:
         logging.warning("Failed to find EXAMPLES assignment")
         return
@@ -135,10 +133,10 @@ def update_examples(bodypart, module_name, collection):
 
 
 def update_short_description(retrn, documentation, module_name):
-    """
-    Update the short description of the module
+    """Update the short description of the module.
 
-    :param bodypart: The DOCUMENTATION section of the module
+    :param retrn: The RETURN section of the module
+    :param documentation: The DOCUMENTATION section of the module
     :param module_name: The module name
     """
     if not retrn:
@@ -186,8 +184,7 @@ def update_short_description(retrn, documentation, module_name):
 
 
 def black(filename):
-    """
-    Run black against the file
+    """Run black against the file.
 
     :param filename: The full path to the file
     """
@@ -196,8 +193,10 @@ def black(filename):
 
 
 def process(collection, path):
-    """
-    Process the files in each subdirectory
+    """Process the files in each subdirectory.
+
+    :param collection: The name of the collection
+    :param path: The collections path
     """
     for subdir in SUBDIRS:
         dirpath = f"{path}{collection}/plugins/{subdir}"
@@ -257,9 +256,7 @@ def process(collection, path):
 
 
 def main():
-    """
-    The entry point
-    """
+    """Run the script."""
     if not platform.python_version().startswith("3.8"):
         sys.exit("Python 3.8+ required")
     parser = ArgumentParser()